> ## 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.
# List Policies
> Filter and list Policies by Envrionment (required), Authorization Workspace, Application, Customer Attributes within an Environment.
Notice
Accessing the API call is through a dedicated domain/URL, according to your PlainID Tenant LocationUnited 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.
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 |
| Content-Type * | `application/json` | `-H "Content-Type:application/json"` |
| Accept | `application/json` | `-H "Accept:application/json"` |
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.
## OpenAPI
````json POST /api/1.0/policies-search/{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:
| Region | Base URL |
|---|
| United States (US) | https://api.us1.plainid.io |
| Canada (CA) | https://api.ca1.plainid.io |
| Europe (EU) | https://api.eu1.plainid.io |
| Local PAA | https://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"
}
],
"tags": [
{
"name": "access-file-authorizer-oas",
"description": "access-file-authorizer-oas"
},
{
"name": "authz-packager-oas",
"description": "authz-packager-oas"
},
{
"name": "SQL Database Authorizer",
"description": "API for modifying SQL queries based on authorization policies"
},
{
"name": "delegated-admin-oas",
"description": "delegated-admin-oas"
},
{
"name": "Discovery",
"description": "Discovery APIs"
},
{
"name": "Enrichment",
"description": "Enrichment APIs"
},
{
"name": "env-mgmt-oas",
"description": "env-mgmt-oas"
},
{
"name": "hybrid-commander-oas",
"description": "hybrid-commander-oas"
},
{
"name": "auth-keys",
"description": "Auth key operations"
},
{
"name": "components",
"description": "Component operations"
},
{
"name": "paas",
"description": "PAA operations"
},
{
"name": "paa-groups",
"description": "PAA group operations"
},
{
"name": "packages",
"description": "Package configuration operations"
},
{
"name": "secret-stores",
"description": "Secret store operations"
},
{
"name": "Table Mapping",
"description": "Table Mapping"
},
{
"name": "Column Mapping",
"description": "Column Mapping"
},
{
"name": "Api Mapping",
"description": "Api Mapping"
},
{
"name": "notifier-oas",
"description": "notifier-oas"
},
{
"name": "shadow-tracker",
"description": "Shadow tracker SSE stream"
},
{
"name": "orchestrator-oas",
"description": "orchestrator-oas"
},
{
"name": "POP",
"description": "pop operations"
},
{
"name": "org-mgmt-oas",
"description": "org-mgmt-oas"
},
{
"name": "pip-mgmt-oas",
"description": "pip-mgmt-oas"
},
{
"name": "monitor-loggers",
"description": "monitor-loggers"
},
{
"name": "Policy Management APIs",
"description": "Policy Management APIs"
},
{
"name": "Policy Management APIs 1.0",
"description": "Policy Management APIs 1.0"
},
{
"name": "Policy Management APIs 2.0",
"description": "Policy Management APIs 2.0"
},
{
"name": "Policy Building Blocks Management APIs 2.0",
"description": "Policy Building Blocks Management APIs 2.0"
},
{
"name": "Audit",
"description": "Audit"
},
{
"name": "Asset Template",
"description": "Asset Template"
},
{
"name": "Application",
"description": "Application"
},
{
"name": "Api Mapper",
"description": "Api Mapper"
},
{
"name": "Identity Template",
"description": "Identity Template"
},
{
"name": "Identity Sources",
"description": "Identity Sources"
},
{
"name": "Mapper Sets",
"description": "Mapper Sets"
},
{
"name": "Identity Template V2",
"description": "Identity Template V2"
},
{
"name": "PAA Sources",
"description": "PAA Sources"
},
{
"name": "PAA Views",
"description": "PAA Views"
},
{
"name": "PAA Groups",
"description": "PAA Groups"
},
{
"name": "Scope",
"description": "Managed Scope APIs"
},
{
"name": "Authentication for Management APIs",
"description": "Authentication for Management APIs"
},
{
"name": "runtime",
"description": "runtime"
},
{
"name": "Cache Management",
"description": "Cache invalidation operations for Runtime service"
}
],
"externalDocs": {
"url": "https://docs.plainid.io/apidocs/policy-management-apis"
},
"paths": {
"/api/1.0/policies-search/{envId}": {
"post": {
"tags": [
"Policy Management APIs 1.0"
],
"summary": "List Policies",
"operationId": "listPolicies",
"description": "Filter and list Policies by Envrionment (required), Authorization Workspace, Application, Customer Attributes within an Environment.
\nNotice
Accessing the API call is through a dedicated domain/URL, according to your PlainID Tenant LocationUnited States (US) - `https://api.us1.plainid.io`Canada (CA) - `https://api.ca1.plainid.io`Europe (EU) - `https://api.eu1.plainid.io`
\nUsing 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.
\nImportant 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 |
| Content-Type * | `application/json` | `-H \"Content-Type:application/json\"` |
| Accept | `application/json` | `-H \"Accept:application/json\"` |
\ncURL 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": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "envId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "The Environment ID can be found under the Details Tab in the Environment Settings.",
"example": "2d4a0591-dfe4-45fb-8a69-d183f5c75c0d"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1
},
"description": "Page size. Default 50, max 100. Capped to 10 when `detailed=true`.",
"example": 50
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 0,
"minimum": 0
},
"description": "Zero-based offset. Default 0.",
"example": 0
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"applicationIds": {
"type": "array",
"description": "Application IDs to filter by. Use a comma within the brackets to specify multiple Application IDs.",
"items": {
"type": "string"
},
"example": [
"my-app-1",
"my-app-2"
]
},
"authzWsIds": {
"type": "array",
"description": "Policy Workspace IDs (previously Authorization Workspace ID) to filter by.",
"items": {
"type": "string",
"format": "uuid"
},
"example": [
"03d54e5b-32ef-4ebe-8bb2-8b9b03049d81"
]
},
"state": {
"type": "string",
"description": "Filter by Policy state.",
"enum": [
"active",
"inactive"
],
"example": "active"
},
"policyCustomAttributes": {
"type": "object",
"description": "Custom Attribute filters expressed as key-value conditions.
- Within a single attribute value list, conditions are evaluated using OR semantics.
-Across different attribute keys, conditions are evaluated using AND semantics.
For more information about Policy Customer Attributes, refer to our documentation.",
"additionalProperties": {
"type": "array",
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
}
]
}
},
"example": {
"regulatoryTags": [
"GDPR-PII"
],
"policyScore": [
2
]
}
},
"actionIds": {
"description": "Action IDs to filter by. Only Policies linked to at least one of the given Actions are returned.
Within this list, conditions are evaluated using OR semantics. Against the other filters, they are evaluated using AND semantics.
Can be used in combination with the `assetTemplateIDs` parameter",
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
},
"example": [
"read",
"Approve"
]
},
"assetTemplateIds": {
"description": "Asset Template IDs to filter by. Only Policies linked to at least one of the given Asset Templates are returned. Within this list, conditions are evaluated using OR semantics. Against the other filters, including `actionIds` they are evaluated using AND semantics.",
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
},
"example": [
"Bank_accounts",
"Claims"
]
},
"detailed": {
"type": "boolean",
"description": "When set to `true`, includes Policy ID and metadata.
When set to `false` (default), only Policy IDs are returned.",
"default": false,
"example": false
}
}
},
"examples": {
"Search Active Policies by App": {
"value": {
"applicationIds": [
"my-app-1"
],
"state": "active",
"detailed": false
}
},
"Search Policies by Action": {
"value": {
"actionIds": [
"read",
"Approve"
],
"detailed": false
}
},
"Search Policies by Asset Template": {
"value": {
"assetTemplateIds": [
"Bank_accounts"
],
"detailed": false
}
},
"Search Policies by Action on one Asset Template": {
"value": {
"actionIds": [
"view"
],
"assetTemplateIds": [
"Bank_accounts"
],
"detailed": false
}
},
"Search with Custom Attributes": {
"value": {
"policyCustomAttributes": {
"regulatoryTags": [
"GDPR-PII"
],
"policyScore": [
2
]
},
"detailed": false
}
},
"Detailed Search with Structured Rego": {
"value": {
"applicationIds": [
"my-app-1"
],
"detailed": true
}
},
"All Parameters": {
"value": {
"applicationIds": [
"my-app-1",
"my-app-2"
],
"authzWsIds": [
"03d54e5b-32ef-4ebe-8bb2-8b9b03049d81"
],
"state": "active",
"policyCustomAttributes": {
"regulatoryTags": [
"GDPR-PII"
],
"policyScore": [
2
]
},
"actionIds": [
"read",
"Approve"
],
"assetTemplateIds": [
"Bank_accounts"
],
"detailed": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Paginated list of policies",
"headers": {
"x-request-id": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"policyId": {
"type": "string",
"description": "The Policy ID."
},
"displayName": {
"type": "string",
"description": "The Policy display name."
},
"state": {
"type": "string",
"description": "Whether the Policy is active or inactive.",
"enum": [
"Active",
"Inactive"
]
},
"accessType": {
"type": "string",
"description": "Whether the Policy allows or restricts access.",
"enum": [
"Allow",
"Restrict"
]
},
"structuredRego": {
"type": "string",
"description": "Structured Rego code wrapped in JSON. Only present when `detailed=true`."
}
}
}
},
"meta": {
"type": "object",
"description": "Response Meta",
"properties": {
"total": {
"type": "integer",
"description": "Total number of matching policies."
},
"limit": {
"type": "integer",
"description": "Page size used for this request."
},
"offset": {
"type": "integer",
"description": "Offset used for this request."
}
}
}
}
},
"examples": {
"Policies Retrieved Successfully": {
"value": {
"data": [
{
"policyId": "POL-001",
"displayName": "US Gold Tier Access Policy",
"state": "Active",
"accessType": "Allow"
},
{
"policyId": "POL-002",
"displayName": "EU Restricted Policy",
"state": "Active",
"accessType": "Restrict"
}
],
"meta": {
"total": 237,
"limit": 50,
"offset": 0
}
}
},
"Detailed Response with Structured Rego": {
"value": {
"data": [
{
"policyId": "POL-001",
"displayName": "US Gold Tier Access Policy",
"state": "Active",
"accessType": "Allow",
"structuredRego": "# METADATA\n# custom:\n# plainid:\n# policyId: 7fa130f2-44d4-4cd1-9590-7cb7fd15f558\n# name: GDPRPolicy\n# accessType: Allow\n# policyUse: DYNAMIC_AUTHORIZATION_SERVICE\n# sourceEnvironmentId: a8663674-c7cf-44e4-b9c5-e9adb513c5d2\n# applications: \n# - id: App\n# customAttributes:\n# regulatoryTags: [\"GDPR-PII\"]\n# policyScore: 2\npackage policy\nimport rego.v1\n\n# METADATA\n# custom:\n# plainid:\n# kind: DynamicGroup\n# name: import All Users\n# id: 38e3b716-8dcd-4ed7-a7b3-beeb15eeca0d\n# description: \"Predefined Dynamic Group. All Users contains all organization's users defined in the IDP\"\ndynamic_group(identity) if {\n\tidentity.template == \"import\"\n}\n\n# METADATA\n# custom:\n# plainid:\n# kind: Ruleset\n# name: All\n# id: 6a4fa454-e4b9-4b02-b543-0ad902fd9f02\n# description: \"Predefined Ruleset. All Assets contains all created assets defined in the Asset Type\"\nruleset(asset, identity, requestParams, action) if {\n\tasset.template == \"Claims\"\n\taction.id in [\"Access\"]\n}"
}
],
"meta": {
"total": 1,
"limit": 10,
"offset": 0
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"headers": {
"x-request-id": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-request-id": {
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "Validation Failed - an empty list was sent for a filter, or a filter matched too many rows to resolve",
"headers": {
"x-request-id": {
"schema": {
"type": "string"
}
}
}
},
"500": {
"description": "Internal Server Error",
"headers": {
"x-request-id": {
"schema": {
"type": "string",
"format": "uuid"
},
"description": "The ID of the request"
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": " 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`"
}
}
}
}
````