> ## Documentation Index > Fetch the complete documentation index at: https://docs.plainid.io/llms.txt > Use this file to discover all available pages before exploring further. # Import Policy > This API call is used to create new Policies, update existing Policies and promote Policies between Environments. Only valid Policies will be created successfully.
For more information, refer to out documentation on Policy Evaluation Logic.
In the **Try It** section, view examples and code samples based on **Response format**, **Content Type (next to the Body title)**, and **Body** dropdowns.

Notice

Accessing the Policy Management APIs is through a dedicated domain/URL, according to your PlainID Tenant Location
  • United States (US) - `https://api.us1.plainid.io`
  • Canada (CA) - `https://api.ca1.plainid.io`
  • Europe (EU) - `https://api.eu1.plainid.io`

    • Using HTML Encoded Special Characters

    Use HTML encoded patterns when working with values that contain special characters like spaces, dashes, etc. Refer to this HTML URL Encoding Reference for a full list.


    Prerequisites

    The following objects need to be available in the target Environment to successfully import the code:

  • Identity Templates in the target Environment with relevant Identity Attributes defined in the Identity Workspace Settings screen.
  • Asset Templates in the target Environment with associated Asset Attributes and Actions defined in the Asset Type Settings screen.

    • The following objects need to be available in the target Environment for Policies created to be considered in the access decision:

  • Asset Types used in the Policy should be connected to an Application defined in the Applications area of the Authorization Workspace.
  • The relevant Application should be connected to a Scope defined in the Environment settings.

    • These connections can be defined before or after importing the Policy.Without these objects, the Policies can be successfully imported, but will not be considered as part of the Access decisions calculation.

    Important note about headers

    Refer to the headers below to modify your cURL sample. Check if the following headers are in the sample, if not, ensure you add it to your cURL sample before pasting into your API tool.

    Headers

    *Required
    Header Value cURL Line
    Accept `text/plain;language=rego` or `application/json` `-H "Accept:text/plain;language=rego"` or `-H "Accept:application/json"`
    Content-Type`text/plain;language=rego` or `application/json` `-H "Content-Type:text/plain;language=rego"` or `-H "Content-Type:application/json"`
    Note: Use text/plain;language=rego when writing Rego in the body.
    Use application/json when writing either Structured or Native code. See the examples below for more information.

    cURL Sample Guidelines

    In order for the relevant parameters to appear in the cURL sample, you can input the values in the interactive API console on the right in the Try It or Code Sample tabs. You can then copy the cURL sample from the Code Sample tab in the correct format.

    ## OpenAPI ````json POST /api/2.0/policies/{envId} { "openapi": "3.0.3", "info": { "title": "Management APIs", "version": "1.0.0", "contact": { "name": "PlainID", "url": "https://plainid.com", "email": "contact@plainid.com" }, "license": { "name": "Commercial", "url": "https://plainid.com/license" }, "termsOfService": "https://www.plainid.com/terms/", "description": "

    The PlainID Authorization Platform provides Management capabilities through the APIs below.

    To access the Management APIs, make sure to enter your dedicated domain according to your PlainID Tenant Location:
    RegionBase URL
    United States (US)https://api.us1.plainid.io
    Canada (CA)https://api.ca1.plainid.io
    Europe (EU)https://api.eu1.plainid.io
    Local PAAhttps://api.plainid.local
    " }, "servers": [ { "description": "United States", "url": "https://api.us1.plainid.io" }, { "description": "Europe", "url": "https://api.eu1.plainid.io" }, { "description": "Canada", "url": "https://api.ca1.plainid.io" }, { "description": "Local PAA", "url": "https://api.plainid.local" } ], "paths": { "/api/2.0/policies/{envId}": { "post": { "tags": [ "Policy Management APIs 2.0" ], "summary": "Import Policy", "description": "This API call is used to create new Policies, update existing Policies and\npromote Policies between Environments. Only valid Policies\nwill be created successfully.
    For more information, refer to out documentation on Policy Evaluation Logic.\n
    In the **Try It** section, view examples and code samples based on **Response format**, **Content Type (next to the Body title)**, and **Body** dropdowns.\n
    \n\n\n\n\n

    Notice

    Accessing the Policy\nManagement APIs is through a dedicated domain/URL, according to your\nPlainID Tenant Location
  • United States (US) -\n`https://api.us1.plainid.io`
  • Canada (CA) -\n`https://api.ca1.plainid.io`
  • Europe (EU) -\n`https://api.eu1.plainid.io`

    • \n\n

    Using HTML Encoded Special Characters

    \n

    Use HTML encoded patterns when working with values that contain special characters like spaces, dashes, etc. Refer to this HTML URL Encoding Reference for a full list.


    \n\n

    Prerequisites

    \n\n

    The following\nobjects need to be available in the target Environment to successfully\nimport the code:

  • Identity Templates in the target Environment\nwith relevant Identity Attributes defined in the Identity Workspace\nSettings screen.
  • Asset Templates in the target Environment with\nassociated Asset Attributes and Actions defined in the Asset Type\nSettings screen.

    • The following objects need to be available in\nthe target Environment for Policies created to be considered in the\naccess decision:

  • Asset Types used in the Policy should be connected\nto an Application defined in the Applications area of the Authorization\nWorkspace.
  • The relevant Application should be connected to a\nScope defined in the Environment settings.

    • These connections can be defined before or after importing the Policy.Without these objects, the Policies can be successfully imported, but will not be\nconsidered as part of the Access decisions calculation.\n
    \n
    \n

    Important note about headers

    \n

    Refer to the headers below to modify your cURL sample. Check if the following headers are in the sample, if not, ensure you add it to your cURL sample before pasting into your API tool.

    \n

    Headers

    \n*Required\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
    HeaderValuecURL Line
    Accept`text/plain;language=rego` or `application/json` `-H \"Accept:text/plain;language=rego\"` or `-H \"Accept:application/json\"`
    Content-Type`text/plain;language=rego` or `application/json``-H \"Content-Type:text/plain;language=rego\"` or `-H \"Content-Type:application/json\"`
    \n\nNote: Use text/plain;language=rego when writing Rego in the body.
    \nUse application/json when writing either Structured or Native code.\nSee the examples below for more information.\n    \n

    cURL Sample Guidelines

    In order for the relevant parameters to appear in the cURL sample, you can input the values in the interactive API console on the right in the Try It or Code Sample tabs. You can then copy the cURL sample from the Code Sample tab in the correct format.

    \n", "operationId": "upsertPolicy", "parameters": [ { "in": "path", "name": "envId", "required": "true", "schema": { "type": "string", "format": "uuid" }, "description": "The Environment ID can be found under the Details Tab in the Environment Settings." }, { "in": "query", "name": "filter[authWsId]", "description": "Authorization Workspace ID. This can be found in your Authorization Workspace Settings under Workspace ID.", "required": "true", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "extendedSchema", "description": "Toggle to either enable or disable additional metadata in the response, like the Policy `id` and `description`.", "schema": { "type": "boolean", "default": "true" } }, { "in": "query", "name": "evaluateByBBName", "description": "Toggle to either enable or disable evaluation by Building Block Name. This controls whether create or update operations locate and/or replace Building Blocks by name, preventing orphaned and duplicate Building Blocks.", "schema": { "type": "boolean", "default": "false" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": "true", "content": { "text/plain;language=rego": { "schema": { "type": "string", "description": "Policy as Rego code" }, "examples": { "Structured Policy": { "value": "# METADATA\n# custom:\n# plainid:\n# policyId: 08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825\n# name: Manage personal account and Credit cards\n# description: Customer can view and manage their own accounts an credit cards only with MFA\n# accessType: Allow\npackage policy\nimport rego.v1\n\n# METADATA\n# custom:\n# plainid:\n# kind: DynamicGroup\n# name: dg1\n# description: \"test DG\"\ndynamic_group(identity) if {\n identity.template == \"idWs1\"\n identity[\"idAttr1\"] == \"test\"\n identity[\"idAttr1\"] != \"prod\"\n}\n" }, "Structured Policy with Generic Condition": { "value": "# METADATA\n# custom:\n# plainid:\n# policyId: 08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825\n# name: Zscaler Country Code Policy\n# description: Policy with generic condition for country codes\n# accessType: Allow\n# policyUse: SAAS_APPLICATIONS\n# sourceEnvironmentId: 9c75b3ac-6165-4a5b-9783-e07dd5d2eb55\n# applications: \n# - id: ZScaler\n# attributes:\n# vendorPolicyKind: \"Access Policy\"\n# ruleOrder: 35\n# name: \"AAAZscalerBugTestZscalerSide\"\n# id: \"72063538272665823\"\npackage policy\nimport rego.v1\n\n# METADATA\n# custom:\n# plainid:\n# kind: Condition\n# subKind: Country Codes\n# name: Albania_Austria_Australia\n# id: 8adc4fe8-759a-4df4-9dc1-c180c9c4a2c4\ncondition(requestParams) if {\n requestParams[\"CountryCode\"] in [\"Albania\", \"Austria\", \"Australia\"]\n}\n" }, "Structured Policy with Multiple Generic Conditions": { "value": "# METADATA\n# custom:\n# plainid:\n# policyId: 08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825\n# name: Zscaler Multi-Condition Policy\n# description: Policy with multiple generic conditions\n# accessType: Allow\n# policyUse: SAAS_APPLICATIONS\n# sourceEnvironmentId: 9c75b3ac-6165-4a5b-9783-e07dd5d2eb55\n# applications: \n# - id: ZScaler\n# attributes:\n# vendorPolicyKind: \"Access Policy\"\n# ruleOrder: 35\n# name: \"AAAZscalerBugTestZscalerSide\"\n# id: \"72063538272665823\"\npackage policy\nimport rego.v1\n\n# METADATA\n# custom:\n# plainid:\n# kind: Condition\n# subKind: Platforms\n# name: c1\n# description: Platform condition\ncondition(requestParams) if {\n requestParams[\"Platform\"] == \"Windows\"\n}\n\n# METADATA\n# custom:\n# plainid:\n# kind: Condition\n# subKind: Country Codes\n# name: Albania_Austria_Australia\n# id: 8adc4fe8-759a-4df4-9dc1-c180c9c4a2c4\ncondition(requestParams) if {\n requestParams[\"CountryCode\"] in [\"Albania\", \"Austria\", \"Australia\"]\n}\n" } } }, "application/json": { "schema": { "$ref": "#/components/schemas/ImportPolicyByFormatRequest" }, "examples": { "Structured Policy": { "value": { "format": "rego", "policy": "# METADATA\n# custom:\n# plainid:\n# policyId: 08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825\n# name: Manage personal account and Credit cards\n# description: Customer can view and manage their own accounts an credit cards only with MFA\n# accessType: Allow\npackage policy\nimport rego.v1\n\n# METADATA\n# custom:\n# plainid:\n# kind: DynamicGroup\n# name: dg1\n# description: \"test DG\"\ndynamic_group(identity) if {\n identity.template == \"idWs1\"\n identity[\"idAttr1\"] == \"test\"\n identity[\"idAttr1\"] != \"prod\"\n}\n" } }, "Structured Policy with Generic Condition": { "value": { "format": "rego", "policy": "# METADATA\n# custom:\n# plainid:\n# policyId: 08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825\n# name: Zscaler Country Code Policy\n# description: Policy with generic condition for country codes\n# accessType: Allow\n# policyUse: SAAS_APPLICATIONS\n# sourceEnvironmentId: 9c75b3ac-6165-4a5b-9783-e07dd5d2eb55\n# applications: \n# - id: ZScaler\n# attributes:\n# vendorPolicyKind: \"Access Policy\"\n# ruleOrder: 35\n# name: \"AAAZscalerBugTestZscalerSide\"\n# id: \"72063538272665823\"\npackage policy\nimport rego.v1\n\n# METADATA\n# custom:\n# plainid:\n# kind: Condition\n# subKind: Country Codes\n# name: Albania_Austria_Australia\n# id: 8adc4fe8-759a-4df4-9dc1-c180c9c4a2c4\ncondition(requestParams) if {\n requestParams[\"CountryCode\"] in [\"Albania\", \"Austria\", \"Australia\"]\n}\n" } }, "Native Policy": { "value": { "format": "json", "policy": { "policyId": "OCP1UUYIIV2DU87", "name": "Bank Account Access Policy", "description": "Policy for accessing bank accounts", "accessType": "Allow", "policyUse": "SAAS_APPLICATIONS", "applications": [ { "applicationId": "POP1V3WFXZ4PRIO", "attributes": { "vendorPolicyKind": "Row Access Policy", "vendorPolicyName": "POL1", "vendorPolicyOrder": "1", "database": "DB", "schema": "SCHEMA", "owner": "ROLE" }, "nativeCode": { "language": "sql", "code": "{\"policy\":\"CREATE OR REPLACE ROW ACCESS POLICY \"POL1\"\"}" } } ] } } } } } } }, "responses": { "201": { "description": "successful operation", "content": { "text/plain;language=rego": { "schema": { "type": "string", "description": "Policy as Rego code" }, "examples": { "Imported Structured Policy": { "value": "# METADATA\n# custom:\n# plainid:\n# policyId: 08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825\n# name: Manage personal account and Credit cards\n# description: Customer can view and manage their own accounts an credit cards only with MFA\n# accessType: Allow\npackage policy\nimport rego.v1\n\n# METADATA\n# custom:\n# plainid:\n# kind: DynamicGroup\n# name: dg1\n# id: f28c17c2-caeb-4cf2-a549-02bf03fe4e17\n# description: \"test DG\"\ndynamic_group(identity) if {\n identity.template == \"idWs1\"\n identity[\"idAttr1\"] == \"test\"\n identity[\"idAttr1\"] != \"prod\"\n}\n" } } }, "application/json": { "schema": { "$ref": "#/components/schemas/ImportPolicyByFormatResponse" }, "examples": { "Structured Policy Response": { "value": { "data": { "format": "rego", "Structured Policy": "# METADATA\n# custom:\n# plainid:\n# policyId: 08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825\n# name: Manage personal account and Credit cards\n# description: Customer can view and manage their own accounts an credit cards only with MFA\n# accessType: Allow\npackage policy\nimport rego.v1\n\n# METADATA\n# custom:\n# plainid:\n# kind: DynamicGroup\n# name: dg1\n# description: \"test DG\"\ndynamic_group(identity) if {\n identity.template == \"idWs1\"\n identity[\"idAttr1\"] == \"test\"\n identity[\"idAttr1\"] != \"prod\"\n}\n", "isPolicyCompleted": "true" } } }, "Native Policy Response": { "value": { "data": { "format": "json", "policy": { "policyId": "OCP1UUYIIV2DU87", "name": "Bank Account Access Policy", "description": "Policy for accessing bank accounts", "accessType": "Allow", "policyUse": "SAAS_APPLICATIONS", "applications": [ { "applicationId": "POP1V3WFXZ4PRIO", "attributes": { "vendorPolicyKind": "Row Access Policy", "vendorPolicyName": "POL1", "vendorPolicyOrder": "1", "database": "DB", "schema": "SCHEMA", "owner": "ROLE" }, "nativeCode": { "language": "sql", "code": "{\"policy\":\"CREATE OR REPLACE ROW ACCESS POLICY \"POL1\"\"}" } } ] }, "isPolicyCompleted": "true" } } } } } }, "headers": { "x-request-id": { "schema": { "type": "string" } } } }, "400": { "description": "bad request", "headers": { "x-request-id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "Authorization WS not found": { "value": { "errors": [ { "code": "PAC-001", "args": { "0": "ceef5853-1491-4d1c-ae52-2f2a1729b3a4" }, "id": "EWWOTR", "status": "400", "name": "AuthorizationWsNotFound", "message": "AuthorizationWs: [ceef5853-1491-4d1c-ae52-2f2a1729b3a4] not found" } ] } } } } } }, "401": { "description": "Unauthorized", "headers": { "x-request-id": { "schema": { "type": "string" } } } }, "422": { "description": "Validation Failed - Invalid UUID", "headers": { "x-request-id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "Invalid ID Format": { "value": { "errors": [ { "code": "V-032", "args": { "0": "ed252aa5-9d0c-4193-838-60bf20b13109", "1": "uuid" }, "id": "EEJQMA", "status": "422", "name": "UnprocessableEntityError", "message": "$: test is an invalid uuid" } ] } } } } } } } } } }, "components": { "schemas": { "ImportPolicyByFormatRequest": { "type": "object", "description": "Request body for importing policies by format", "required": [ "format", "policy" ], "properties": { "format": { "$ref": "#/components/schemas/PolicyFormat" }, "policy": { "type": "object", "description": "Policy content based on format" } } }, "ImportPolicyByFormatResponse": { "type": "object", "description": "Response object for import policy by format endpoint", "properties": { "data": { "type": "object", "description": "Import policy response data", "properties": { "format": { "$ref": "#/components/schemas/PolicyFormat" }, "policy": { "type": "object", "description": "Policy content based on format" }, "isPolicyCompleted": { "type": "boolean", "description": "Whether the policy is completed" } } } } }, "Errors": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "PolicyFormat": { "type": "string", "enum": [ "rego", "json" ], "description": "Policy format type", "example": "rego" }, "Error": { "type": "object", "properties": { "code": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" }, "args": { "type": "object", "properties": { "path": { "type": "string" } } } } } } } } ````