> ## 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.

# Identity Cache Invalidation

> Performs a cache invalidation operation for identity data in the PAAs related to the relevant Environment.<br> <br>
<h3>When to use this API</h3> 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.<br>
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. <br>
<h3>Using this API</h3>
<h4>Authentication</h4> A valid PlainID Platform JWT is required in the `Authorization` header. Refer to our <a href="https://docs.plainid.io/apidocs/get-access-token">Get Access Token API</a> to retrieve a valid JWT for the Bearer Token.  <br> <br> <h4>How to use this API</h4> Provide at least one of <code>identityTemplate</code> or <code>identityId</code> in the request body.<br> To invalidate all identity caches for a specific template in Environment's PAAs, send a JSON object in the request body with the <b>Identity Template ID only</b>. The <code>identityId</code> 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 <b>Identity Template ID only</b>.  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: <ul>
  <li><b>Attribute Source ID:</b> Limits invalidation to Identity  data from a specific Identity Attribute source, which is defined as part of your Identity Template.<ul><li>If only the Attribute Source ID is provided, all cached identity data for that source will be invalidated across all users.</li></ul></li>
  <li><b>Identity ID:</b> 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.<ul><li>If only the Identity ID is provided, the user's identity data will be invalidated across all cached sources.</li></ul></li> <li>If both parameters are provided, the identity data for the specified user and source will be invalidated.</li> </ul>




<h3>Notice</h3> When accessing the Authorization APIs, the URL base/prefix depends on your PlainID PDP location: <li><b>United States Cloud PDP</b> - `https://tenant-name.us1.plainid.io`</li> <li><b>Canadian Cloud PDP</b> - `https://tenant-name.ca1.plainid.io`</li> <li><b>European Cloud PDP</b> - `https://tenant-name.eu1.plainid.io`</li><li><b>Local PAA</b> - `https://your-paa.acme.local`</li> <br>
For more information on which Asset Types to use with your PAA or Cloud PDP, refer to <a href="https://docs.plainid.io/docs/managing-asset-types">Managing Asset Types</a>.<br>
<h3>cURL Sample Guidelines</h3> <p>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.</p> <p><i>\*Try It function coming soon.</i></p><br>
<h3>Important note about headers</h3> <p>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.</p>
<h3>Headers</h3> <table>
  <thead>
    <tr>
      <th>Header</th>
      <th>Value</th>
      <th>cURL Line</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Accept</td>
      <td><code>application/json</code></td>
      <td><code>'accept: application/json'</code></td>
    </tr>
    <tr>
      <td>Content-Type</td>
      <td><code>application/json</code></td>
      <td><code>'content-type: application/json'</code></td>
    </tr>
    <tr>
      <td>X-Request-ID (optional)</td>
      <td><code>UUID</code></td>
      <td><code>'X-Request-ID: {uuid}'</code></td>
    </tr>
  </tbody>
</table> <br>
Note: <b>RequestID Header (optional):</b> You may include an <code>X-Request-ID</code> header for traceability. If not provided, the system will generate one automatically. <br><br>

## OpenAPI

````json POST /api/1.0/runtime/caches/identity/{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/identity/{envId}/invalidate": {
      "post": {
        "tags": [
          "Cache Management"
        ],
        "summary": "Identity Cache Invalidation",
        "operationId": "InvalidateIdentityCache",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Performs a cache invalidation operation for identity data in the PAAs related to the relevant Environment.<br> <br>\n<h3>When to use this API</h3> 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.<br>\nExample 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. <br>\n<h3>Using this API</h3>\n<h4>Authentication</h4> A valid PlainID Platform JWT is required in the `Authorization` header. Refer to our <a href=\"https://docs.plainid.io/apidocs/get-access-token\">Get Access Token API</a> to retrieve a valid JWT for the Bearer Token.  <br> <br> <h4>How to use this API</h4> Provide at least one of <code>identityTemplate</code> or <code>identityId</code> in the request body.<br> To invalidate all identity caches for a specific template in Environment's PAAs, send a JSON object in the request body with the <b>Identity Template ID only</b>. The <code>identityId</code> 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 <b>Identity Template ID only</b>.  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: <ul>\n  <li><b>Attribute Source ID:</b> Limits invalidation to Identity  data from a specific Identity Attribute source, which is defined as part of your Identity Template.<ul><li>If only the Attribute Source ID is provided, all cached identity data for that source will be invalidated across all users.</li></ul></li>\n  <li><b>Identity ID:</b> 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.<ul><li>If only the Identity ID is provided, the user's identity data will be invalidated across all cached sources.</li></ul></li> <li>If both parameters are provided, the identity data for the specified user and source will be invalidated.</li> </ul>\n\n\n\n\n<h3>Notice</h3> When accessing the Authorization APIs, the URL base/prefix depends on your PlainID PDP location: <li><b>United States Cloud PDP</b> - `https://tenant-name.us1.plainid.io`</li> <li><b>Canadian Cloud PDP</b> - `https://tenant-name.ca1.plainid.io`</li> <li><b>European Cloud PDP</b> - `https://tenant-name.eu1.plainid.io`</li><li><b>Local PAA</b> - `https://your-paa.acme.local`</li> <br>\nFor more information on which Asset Types to use with your PAA or Cloud PDP, refer to <a href=\"https://docs.plainid.io/docs/managing-asset-types\">Managing Asset Types</a>.<br>\n<h3>cURL Sample Guidelines</h3> <p>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.</p> <p><i>\\*Try It function coming soon.</i></p><br>\n<h3>Important note about headers</h3> <p>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.</p>\n<h3>Headers</h3> <table>\n  <thead>\n    <tr>\n      <th>Header</th>\n      <th>Value</th>\n      <th>cURL Line</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Accept</td>\n      <td><code>application/json</code></td>\n      <td><code>'accept: application/json'</code></td>\n    </tr>\n    <tr>\n      <td>Content-Type</td>\n      <td><code>application/json</code></td>\n      <td><code>'content-type: application/json'</code></td>\n    </tr>\n    <tr>\n      <td>X-Request-ID (optional)</td>\n      <td><code>UUID</code></td>\n      <td><code>'X-Request-ID: {uuid}'</code></td>\n    </tr>\n  </tbody>\n</table> <br>\nNote: <b>RequestID Header (optional):</b> You may include an <code>X-Request-ID</code> header for traceability. If not provided, the system will generate one automatically. <br><br>",
        "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 true, returns a structured success payload with a textual summary and invalidated keys count."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvalidateIdentityCacheRequest"
              },
              "examples": {
                "fullInvalidation": {
                  "summary": "Invalidate all identity caches for a template",
                  "value": {
                    "identityTemplate": "User"
                  }
                },
                "specificUser": {
                  "summary": "Invalidate specific user's identity cache",
                  "value": {
                    "identityTemplate": "User",
                    "identityId": "john.doe@example.com"
                  }
                },
                "userAcrossTemplates": {
                  "summary": "Invalidate a specific user across all templates in the environment",
                  "value": {
                    "identityId": "john.doe@example.com"
                  }
                },
                "specificSource": {
                  "summary": "Invalidate specific attribute source",
                  "value": {
                    "identityTemplate": "User",
                    "attributeSourceId": "3cb6e371-c76b-408d-a9cb-6d4b260145b0"
                  }
                },
                "userAndSource": {
                  "summary": "Invalidate specific user from specific source",
                  "value": {
                    "identityTemplate": "User",
                    "identityId": "john.doe@example.com",
                    "attributeSourceId": "3cb6e371-c76b-408d-a9cb-6d4b260145b0"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Identity cache invalidated successfully. Returns an empty 200 response by default; when verbose=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": "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"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Missing required parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericErrorsArray"
                },
                "examples": {
                  "missingIdentityTemplate": {
                    "summary": "Missing required identityTemplate or identityId parameter",
                    "value": {
                      "errors": [
                        {
                          "code": "ERR-001",
                          "status": "400",
                          "name": "InvalidRequest",
                          "message": "Either identityTemplate or identityId must be provided"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "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": {
      "InvalidateIdentityCacheRequest": {
        "type": "object",
        "description": "Provide at least one of <code>identityTemplate</code> or <code>identityId</code>.<br> To invalidate all identity caches in Environment's PAAs for a specific template, send a JSON object in the request body with the <b>Identity Template ID only</b>. To invalidate a single user across all templates in the environment, send <code>identityId</code> only.",
        "properties": {
          "identityTemplate": {
            "type": "string",
            "description": "The Identity Template ID where the identity is defined. Optional when <code>identityId</code> is provided. You can find this in your Identity Workspace Settings. For more information, refer to <a href=\"https://docs.plainid.io/docs/identity-workspace-settings\">Identity Workspace Settings</a> in the PlainID documentation.",
            "example": "User"
          },
          "attributeSourceId": {
            "type": "string",
            "description": "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 <a href=\"https://docs.plainid.io/v1/docs/managing-attribute-sources\">Managing Attribute Sources</a> in the PlainID documentation.",
            "example": "3cb6e371-c76b-408d-a9cb-6d4b260145b0"
          },
          "identityId": {
            "type": "string",
            "description": "The Identity UID to invalidate, as modeled and mapped in the Identity Template. <i>Note: This is the same user ID that is used when sending an Authorization request with the `entityId` parameter.</i> Optional when <code>identityTemplate</code> is provided, and required if <code>identityTemplate</code> is absent.",
            "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"
        ]
      }
    }
  }
}
````