Performs a cache invalidation operation for identity data in the PAAs related to the relevant Environment.
When to use this API
Use this API when identity-related data changes—such as group membership, attribute values, or source assignments—and you want to immediately clear outdated entries from the Identity cache.Example Use Case: Identity data is cached for each user during the first Authorization request and will be invalidated when the user logs off an Application. So during the next login to the Application, fresh data will be re-fetched for the current Authorization session.
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 use this API
Provide at least one ofidentityTemplate or identityId in the request body.To invalidate all identity caches for a specific template in Environment's PAAs, send a JSON object in the request body with the Identity Template ID only. The
identityId is optional when identityTemplate is provided, and required if identityTemplate is absent. To invalidate all identity caches for a specific template in Environment's PAAs, send a JSON object in the request body with the Identity Template ID only. The invalidation can be applied broadly for all Identity Source data and for all users, or scoped down using these **optional** parameters in the request body: - Attribute Source ID: Limits invalidation to Identity data from a specific Identity Attribute source, which is defined as part of your Identity Template.
- If only the Attribute Source ID is provided, all cached identity data for that source will be invalidated across all users.
- Identity ID: Invalidates dentity data for a specific user, identified by the unique identifier (UID) as defined in the Identity template. This clears any cached data associated with that user.
- If only the Identity ID is provided, the user's identity data will be invalidated across all cached sources.
- If both parameters are provided, the identity data for the specified user and source will be 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 an
X-Request-ID 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 true, returns a structured success payload with a textual summary and invalidated keys count.
Invalidate all identity caches for a template
{
"identityTemplate": "User"
}Invalidate specific user's identity cache
{
"identityTemplate": "User",
"identityId": "john.doe@example.com"
}Invalidate a specific user across all templates in the environment
{
"identityId": "john.doe@example.com"
}Invalidate specific attribute source
{
"identityTemplate": "User",
"attributeSourceId": "3cb6e371-c76b-408d-a9cb-6d4b260145b0"
}Invalidate specific user from specific source
{
"identityTemplate": "User",
"identityId": "john.doe@example.com",
"attributeSourceId": "3cb6e371-c76b-408d-a9cb-6d4b260145b0"
}Provide at least one of identityTemplate or identityId.
To invalidate all identity caches in Environment's PAAs for a specific template, send a JSON object in the request body with the Identity Template ID only. To invalidate a single user across all templates in the environment, send identityId only.
The Identity Template ID where the identity is defined. Optional when identityId is provided. You can find this in your Identity Workspace Settings. For more information, refer to Identity Workspace Settings in the PlainID documentation.
The identifier of the Attribute Source to limit the invalidation to identities from a specific source. For information on the sourceID parameter and where to locate it, check out Managing Attribute Sources in the PlainID documentation.
The Identity UID to invalidate, as modeled and mapped in the Identity Template. Note: This is the same user ID that is used when sending an Authorization request with the entityId parameter. Optional when identityTemplate is provided, and required if identityTemplate is absent.
Identity cache invalidated successfully. Returns an empty 200 response by default; when verbose=true, returns a structured success payload.
Successful verbose cache invalidation
{
"status": "success",
"operation": "identity",
"message": "Invalidated 37 identity cache keys for user john.doe@example.com across 4 identity templates",
"invalidatedKeysCount": 37,
"requestId": "7d0f56ff-7816-4565-ac07-4cd772e196ea",
"targets": {
"environmentId": "08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825",
"identityId": "john.doe@example.com"
}
}Verbose success payload returned when the verbose query parameter is true.
Bad Request - Missing required parameters
Missing required identityTemplate or identityId parameter
{
"errors": [
{
"code": "ERR-001",
"status": 400,
"name": "InvalidRequest",
"message": "Either identityTemplate or identityId must be provided"
}
]
}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"
}
]
}