> ## 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. # PDP Response Cache Invalidation > 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:

Notice

When accessing the Authorization APIs, the URL base/prefix depends on your PlainID PDP location:
  • United States Cloud PDP - `https://tenant-name.us1.plainid.io`
  • Canadian Cloud PDP - `https://tenant-name.ca1.plainid.io`
  • European Cloud PDP - `https://tenant-name.eu1.plainid.io`
  • Local PAA - `https://your-paa.acme.local`

    • 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

    HeaderValuecURL Line
    Acceptapplication/json'accept: application/json'
    Content-Typeapplication/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.

    ## OpenAPI ````json POST /api/1.0/runtime/caches/response/{envId}/invalidate { "openapi": "3.0.3", "info": { "title": "Authorization APIs", "version": "1.0", "description": "Applications, services, and authorizers use the Authorization APIs to receive the PlainID Access Decision from the PDP", "contact": { "name": "PlainID", "url": "https://plainid.com", "email": "contact@plainid.com" }, "termsOfService": "https://plainid.com/terms", "license": { "name": "Commercial", "url": "https://plainid.com/license" } }, "servers": [ { "description": "United States", "url": "https://tenant-name.us1.plainid.io" }, { "description": "Europe", "url": "https://tenant-name.eu1.plainid.io" }, { "description": "Canada", "url": "https://tenant-name.ca1.plainid.io" }, { "description": "Local PAA", "url": "https://your-paa.acme.local" } ], "paths": { "/api/1.0/runtime/caches/response/{envId}/invalidate": { "post": { "tags": [ "Cache Management" ], "summary": "PDP Response Cache Invalidation", "operationId": "InvalidateResponseCache", "security": [ { "bearerAuth": [] } ], "description": "Performs a cache invalidation operation for PDP response data in the PAAs related to the relevant Environment.
    \n

    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.
    \n

    Using this API

    \n

    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.

    \n

    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: \n\n\n

    Notice

    When accessing the Authorization APIs, the URL base/prefix depends on your PlainID PDP location:
  • United States Cloud PDP - `https://tenant-name.us1.plainid.io`
  • Canadian Cloud PDP - `https://tenant-name.ca1.plainid.io`
  • European Cloud PDP - `https://tenant-name.eu1.plainid.io`
  • Local PAA - `https://your-paa.acme.local`

    • \nFor more information on which Asset Types to use with your PAA or Cloud PDP, refer to Managing Asset Types.
    \n

    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.


    \n

    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.

    \n

    Headers

    \n \n \n \n
    HeaderValuecURL Line
    Acceptapplication/json'accept: application/json'
    Content-Typeapplication/json'content-type: application/json'
    X-Request-ID (optional)UUID'X-Request-ID: {uuid}'

    \n\nNote: RequestID Header (optional): You may include a `RequestID` in the header for traceability. If not provided, the system will generate one automatically.

    ", "parameters": [ { "name": "envId", "in": "path", "required": "true", "schema": { "type": "string" }, "description": "The Environment ID can be found under the Details Tab in the Environment Settings.", "example": "08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825" }, { "name": "verbose", "in": "query", "required": "false", "schema": { "type": "boolean", "default": "false" }, "example": "false", "description": "When set to `true`, returns a structured success payload with a textual summary and invalidated key count." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidateResponseCacheRequest" }, "examples": { "fullInvalidation": { "summary": "Invalidate all response caches", "value": {} }, "specificScope": { "summary": "Invalidate caches for a specific scope", "value": { "clientId": "PGC64A2B6892DU68B6GV" } }, "multipleScopes": { "summary": "Invalidate caches for multiple scopes", "value": { "clientIds": [ "PGC64A2B6892DU68B6GV", "PGC111111111111111111" ] } }, "specificUser": { "summary": "Invalidate caches for a specific user", "value": { "identityId": "john.doe@example.com" } }, "scopesAndUser": { "summary": "Invalidate caches for specific user in multiple scopes", "value": { "clientIds": [ "PGC64A2B6892DU68B6GV", "PGC111111111111111111" ], "identityId": "john.doe@example.com" } } } } } }, "responses": { "200": { "description": "PDP response cache invalidated successfully. Returns an empty 200 response by default; when verbose is set to `true`, returns a structured success payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CacheInvalidationSuccessResponse" }, "examples": { "verboseSuccess": { "summary": "Successful verbose cache invalidation", "value": { "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" ] } } } } } } }, "400": { "description": "Bad Request - Invalid request format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericErrorsArray" }, "examples": { "invalidRequest": { "summary": "Invalid request body", "value": { "errors": [ { "code": "ERR-002", "status": "400", "name": "InvalidRequest", "message": "Request body must be a valid JSON object" } ] } } } } } }, "401": { "description": "Unauthorized - Invalid or missing JWT token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericErrorsArray" }, "examples": { "unauthorized": { "summary": "Missing or invalid authentication token", "value": { "errors": [ { "code": "ERR-401", "status": "401", "name": "Unauthorized", "message": "Invalid or missing authentication token" } ] } } } } } }, "424": { "description": "Failed Dependency - Unable to connect to cache service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericErrorsArray" }, "examples": { "redisConnectionFailed": { "summary": "Redis connection failure", "value": { "errors": [ { "code": "ERR-424", "status": "424", "name": "FailedDependency", "message": "Unable to connect to Redis cache service" } ] } } } } } } } } } }, "components": { "schemas": { "InvalidateResponseCacheRequest": { "type": "object", "description": "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.", "properties": { "clientId": { "type": "string", "description": "The Scope Client ID used to limit the invalidation to a specific Scope. This can be found in your Platform Environment or Tenant Settings.", "example": "PGC64A2B6892DU68B6GV" }, "clientIds": { "type": "array", "description": "A list of Scope Client IDs used to invalidate multiple scopes in a single request.", "items": { "type": "string" }, "example": [ "PGC64A2B6892DU68B6GV", "PGC111111111111111111" ] }, "identityId": { "type": "string", "description": "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.", "example": "john.doe@example.com" } } }, "CacheInvalidationSuccessResponse": { "type": "object", "description": "Verbose success payload returned when the verbose query parameter is true.", "properties": { "status": { "type": "string", "example": "success" }, "operation": { "type": "string", "example": "response" }, "message": { "type": "string", "example": "Invalidated 124 response cache keys for user john.doe@example.com across 2 scopes" }, "invalidatedKeysCount": { "type": "integer", "format": "int64", "example": "124" }, "requestId": { "type": "string", "example": "e319dc1f-96ef-4ec0-bf8f-a9df42f31ab6" }, "targets": { "$ref": "#/components/schemas/CacheInvalidationTargets" } }, "required": [ "status", "operation", "message", "invalidatedKeysCount", "requestId", "targets" ] }, "GenericErrorsArray": { "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": "true", "minItems": "1", "items": { "$ref": "#/components/schemas/GenericError" } } }, "required": [ "errors" ], "x-examples": { "example-1": { "errors": [ { "id": "XXXX", "code": "YYYY", "message": "Invalid request" } ] } } }, "CacheInvalidationTargets": { "type": "object", "properties": { "environmentId": { "type": "string", "example": "08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825" }, "identityId": { "type": "string", "nullable": "true", "example": "john.doe@example.com" }, "identityTemplate": { "type": "string", "nullable": "true", "example": "User" }, "attributeSourceId": { "type": "string", "nullable": "true", "example": "3cb6e371-c76b-408d-a9cb-6d4b260145b0" }, "clientIds": { "type": "array", "items": { "type": "string" } } } }, "GenericError": { "type": "object", "properties": { "id": { "type": "string", "minLength": "1" }, "code": { "type": "string", "minLength": "1" }, "name": { "type": "string", "minLength": "1" }, "message": { "type": "string", "minLength": "1" } }, "required": [ "id", "code", "message", "name" ] } } } } ````