Import Policy

Updated on Feb 23, 2025
Published on Apr 7, 2024

3 minute(s) read

Post

/api/2.0/policies/{envId}

Note - for the older version, see Import Policy V1.

This API is used to create new Policies, update existing Policies and promote Policies between Environments. Only valid Policies will be created successfully.

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`	`-H "Accept:text/plain;language=rego"`
Content-Type	`text/plain;language=rego`	`-H "Content-Type:text/plain;language=rego"`

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. They will then appear in the cURL sample on the bottom of the page in the correct format.

Security

HTTP

Type bearer

For more details about Administration API Authentication, check out the Authentication APIs documentation. Provide your bearer token in the Authorization header when making requests to protected resources. Example: Authorization: Bearer 123

Path parameters

envId

string (uuid) Required

The Environment ID can be found under the Details tab in the Environment Settings.

Query parameters

filter[authWsId]

string (uuid) Required

Authorization Workspace ID. This can be found in your Authorization Workspace Settings under Workspace ID.

extendedSchema

boolean

Toggle to either enable or disable additional metadata in the response, like the Policy id and description.

Defaulttrue

Body parameters

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"

string

Policy as Rego code

Responses

201

successful operation

Headers

x-request-id

string

Imported 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#     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"

string

Policy as Rego code

400

bad request

Headers

x-request-id

string

Authorization WS not found

{
  "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"
    }
  ]
}

Expand All

object

errors

Array of object (Error)

object

code

string

status

integer

name

string

message

string

args

object

path

string

401

Unauthorized

Headers

x-request-id

string

422

Validation Failed - Invalid UUID

Headers

x-request-id

string

Invalid ID Format

{
  "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"
    }
  ]
}

Expand All

object

errors

Array of object (Error)

object

code

string

status

integer

name

string

message

string

args

object

path

string

Was this article helpful?