> ## 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"
}
],
"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 Id",
"items": {
"type": "string"
},
"example": [
"my-app-1",
"my-app-2"
]
},
"authzWsIds": {
"type": "array",
"description": "Authorization Workspace IDs 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. Values may be strings or numbers. 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"
]
}
},
"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 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"
]
},
"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"
}
}
}
},
"500": {
"description": "Internal Server Error",
"headers": {
"x-request-id": {
"schema": {
"type": "string",
"format": "uuid"
},
"description": "The ID of the request"
}
}
}
}
}
}
}
}
````