Example
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "The requested identity could not be found",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/api-reference/errors-v2/unkey/data/identity_not_found"
  }
}

​
What Happened?

This error occurs when you’re trying to perform an operation on an identity that doesn’t exist in the Unkey system. Identities in Unkey are used to represent users or entities that own or use API keys. Common scenarios that trigger this error:
  • Using an incorrect identity ID or external ID
  • Referencing an identity that has been deleted
  • Trying to update or get information about a non-existent identity
  • Typos in identity identifiers
Here’s an example of a request that would trigger this error: 
# Attempting to get a non-existent identity
curl -X POST https://api.unkey.com/v1/identities.getIdentity \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
  -d '{
    "identityId": "ident_nonexistent"
  }'

​
How To Fix

Verify that you’re using the correct identity ID or external ID and that the identity still exists in your workspace:
  1. Check the identity ID in your request for typos or formatting errors
  2. List all identities in your workspace to find the correct ID
  3. If the identity has been deleted, you may need to recreate it
Here’s how to list identities in your workspace: 
curl -X GET https://api.unkey.com/v1/identities.listIdentities \
  -H "Authorization: Bearer unkey_YOUR_API_KEY"
If you need to create a new identity, use the identities.createIdentity endpoint: 
curl -X POST https://api.unkey.com/v2/identities.createIdentity \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
  -d '{
    "externalId": "user_123",
    "meta": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'

​
Common Mistakes

  • Incorrect identifiers: Using wrong identity IDs or external IDs
  • Deleted identities: Attempting to reference identities that have been removed
  • Case sensitivity: External IDs might be case-sensitive
  • Workspace boundaries: Trying to access identities from another workspace