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

​
What Happened?

This error occurs when you’re trying to perform an operation on a permission that doesn’t exist in the Unkey system. Permissions in Unkey are used to control access to resources and operations. Common scenarios that trigger this error:
  • Using an incorrect permission ID or name
  • Referencing a permission that has been deleted
  • Trying to assign a permission that doesn’t exist in the current workspace
  • Typos in permission names when using name-based lookups
Here’s an example of a request that would trigger this error: 
# Attempting to assign a non-existent permission to a role
curl -X POST https://api.unkey.com/v1/roles.addPermission \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
  -d '{
    "roleId": "role_123abc",
    "permissionId": "perm_nonexistent"
  }'

​
How To Fix

Verify that you’re using the correct permission ID or name and that the permission still exists in your workspace:
  1. List all permissions in your workspace to find the correct ID
  2. Check if the permission has been deleted and recreate it if necessary
  3. Verify you’re working in the correct workspace
Here’s how to list all permissions in your workspace: 
curl -X GET https://api.unkey.com/v1/permissions.listPermissions \
  -H "Authorization: Bearer unkey_YOUR_API_KEY"
If you need to create a new permission, use the appropriate API endpoint: 
curl -X POST https://api.unkey.com/v1/permissions.createPermission \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
  -d '{
    "name": "read:keys",
    "description": "Allows reading key information"
  }'

​
Common Mistakes

  • Incorrect identifiers: Using wrong permission IDs or names
  • Deleted permissions: Referencing permissions that have been removed
  • Case sensitivity: Permissions names might be case-sensitive
  • Workspace boundaries: Trying to use permissions from another workspace