Performs a cache invalidation operation for PDP response data in the PAAs related to the relevant Environment.
When to use this API
Use this API when the Policy decision results (responses) might no longer be valid—such as after Policy changes, updates to Identity Attributes, or Environment configuration changes—and you want to ensure fresh Authorization evaluations at Runtime. Although the cache typically expires based on TTL, this API allows you to proactively clear cached results when immediate re-evaluation is needed.Using this API
Authentication
A valid PlainID Platform JWT is required in the `Authorization` header. Refer to our Get Access Token API to retrieve a valid JWT for the Bearer Token.How to invalidate parameters
To invalidate all response caches in the Environment's PAAs, send an empty JSON object in the request body. The body must always be present, even when performing a full cache invalidation, and this behavior remains supported for backward compatibility.The invalidation can be scoped using these optional parameters in the request body:
- Scope Client ID/s: Clears cached responses associated with a specific Scope.
- If provided, all PDP response cache entries for the specified Scope are invalidated across all responses.
- Identity ID: The unique identifier (UID) of the identity, used to clear cached responses for a specific user.
- If provided, all cached PDP responses for that user across specific Scopes are invalidated.
- If both parameters are provided, the cached PDP responses for the specified user within the specified Scope are invalidated.
Notice
When accessing the Authorization APIs, the URL base/prefix depends on your PlainID PDP location:For more information on which Asset Types to use with your PAA or Cloud PDP, refer to Managing Asset Types.
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 under the Try It\* or the Code Sample tabs. They will then appear in the cURL sample in the correct format to use in your API tool.
\*Try It function coming soon.
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 them before pasting into your API tool.
Headers
| Header | Value | cURL Line |
|---|---|---|
| Accept | application/json | 'accept: application/json' |
| Content-Type | application/json | 'content-type: application/json' |
| X-Request-ID (optional) | UUID |
'X-Request-ID: {uuid}' |
Note: RequestID Header (optional): You may include a RequestID in the header for traceability. If not provided, the system will generate one automatically.
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
The Environment ID can be found under the Details Tab in the Environment Settings.
When set to true, returns a structured success payload with a textual summary and invalidated key count.
Invalidate all response caches
{}Invalidate caches for a specific scope
{
"clientId": "PGC64A2B6892DU68B6GV"
}Invalidate caches for multiple scopes
{
"clientIds": [
"PGC64A2B6892DU68B6GV",
"PGC111111111111111111"
]
}Invalidate caches for a specific user
{
"identityId": "john.doe@example.com"
}Invalidate caches for specific user in multiple scopes
{
"clientIds": [
"PGC64A2B6892DU68B6GV",
"PGC111111111111111111"
],
"identityId": "john.doe@example.com"
}The request body is required — even when performing a full cache invalidation. To clear all PDP response caches in the Environment's PAAs, send an empty JSON object. The selectors clientId, clientIds, and identityId are optional.
The Scope Client ID used to limit the invalidation to a specific Scope. This can be found in your Platform Environment or Tenant Settings.
A list of Scope Client IDs used to invalidate multiple scopes in a single request.
The UID of the identity whose PDP response cache should be invalidated, as modeled in the Identity Template. Note: This is the same user ID that is used when sending an Authorization request with the entityId parameter.
PDP response cache invalidated successfully. Returns an empty 200 response by default; when verbose is set to true, returns a structured success payload.
Successful verbose cache invalidation
{
"status": "success",
"operation": "response",
"message": "Invalidated 124 response cache keys for user john.doe@example.com across 2 scopes",
"invalidatedKeysCount": 124,
"requestId": "e319dc1f-96ef-4ec0-bf8f-a9df42f31ab6",
"targets": {
"environmentId": "08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825",
"identityId": "john.doe@example.com",
"clientIds": [
"PGC64A2B6892DU68B6GV",
"PGC111111111111111111"
]
}
}Verbose success payload returned when the verbose query parameter is true.
Bad Request - Invalid request format
Invalid request body
{
"errors": [
{
"code": "ERR-002",
"status": 400,
"name": "InvalidRequest",
"message": "Request body must be a valid JSON object"
}
]
}Unauthorized - Invalid or missing JWT token
Missing or invalid authentication token
{
"errors": [
{
"code": "ERR-401",
"status": 401,
"name": "Unauthorized",
"message": "Invalid or missing authentication token"
}
]
}Failed Dependency - Unable to connect to cache service
Redis connection failure
{
"errors": [
{
"code": "ERR-424",
"status": 424,
"name": "FailedDependency",
"message": "Unable to connect to Redis cache service"
}
]
}