# Unkey Docs ## Docs - [Using Cursor with Unkey](https://unkey.com/docs/ai-code-gen/cursor.md): Leverage Cursor's AI capabilities to build applications with Unkey's APIs - [AI Code Gen with Unkey](https://unkey.com/docs/ai-code-gen/overview.md): Use AI-powered code generation tools with Unkey's APIs and services - [Unkey MCP (Model Context Protocol)](https://unkey.com/docs/ai-code-gen/unkey-mcp.md): Connect AI tools to Unkey's APIs using Model Context Protocol - [Using Windsurf with Unkey](https://unkey.com/docs/ai-code-gen/windsurf.md): Build applications with Windsurf's AI-powered development environment and Unkey's APIs - [Getting Started](https://unkey.com/docs/analytics/getting-started.md): Request access and run your first analytics query - [Overview](https://unkey.com/docs/analytics/overview.md): Query your verification data with SQL - [Query Examples](https://unkey.com/docs/analytics/query-examples.md): Common SQL patterns for analytics and billing - [Query Restrictions](https://unkey.com/docs/analytics/query-restrictions.md): Limits, quotas, and permissions for analytics queries - [Quick Reference](https://unkey.com/docs/analytics/quick-reference.md): Fast lookup for common analytics query patterns and table selection - [Schema Reference](https://unkey.com/docs/analytics/schema-reference.md): Tables, columns, and data types in Unkey Analytics - [Troubleshooting](https://unkey.com/docs/analytics/troubleshooting.md): Common issues and solutions for analytics queries - [Get verification analytics](https://unkey.com/docs/api-reference/v1/analytics/get-verification-analytics.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Create API namespace](https://unkey.com/docs/api-reference/v1/apis/create-api-namespace.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Delete API keys](https://unkey.com/docs/api-reference/v1/apis/delete-api-keys.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Delete API namespace](https://unkey.com/docs/api-reference/v1/apis/delete-api-namespace.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Get API namespace](https://unkey.com/docs/api-reference/v1/apis/get-api-namespace.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [List API keys](https://unkey.com/docs/api-reference/v1/apis/list-api-keys.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Authentication](https://unkey.com/docs/api-reference/v1/authentication.md): Securely authenticating with the Unkey API - [Create identity](https://unkey.com/docs/api-reference/v1/identities/create-identity.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Delete identity](https://unkey.com/docs/api-reference/v1/identities/delete-identity.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Get identity](https://unkey.com/docs/api-reference/v1/identities/get-identity.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [List identities](https://unkey.com/docs/api-reference/v1/identities/list-identities.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Update identity](https://unkey.com/docs/api-reference/v1/identities/update-identity.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Add key permissions](https://unkey.com/docs/api-reference/v1/keys/add-key-permissions.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Add key roles](https://unkey.com/docs/api-reference/v1/keys/add-key-roles.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Create API key](https://unkey.com/docs/api-reference/v1/keys/create-api-key.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Delete API key](https://unkey.com/docs/api-reference/v1/keys/delete-api-key.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Get API key](https://unkey.com/docs/api-reference/v1/keys/get-api-key.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Get key information](https://unkey.com/docs/api-reference/v1/keys/get-key-information.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Get v1keysgetverifications](https://unkey.com/docs/api-reference/v1/keys/get-v1keysgetverifications.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Remove key permissions](https://unkey.com/docs/api-reference/v1/keys/remove-key-permissions.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Remove key roles](https://unkey.com/docs/api-reference/v1/keys/remove-key-roles.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Set key permissions](https://unkey.com/docs/api-reference/v1/keys/set-key-permissions.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Set key roles](https://unkey.com/docs/api-reference/v1/keys/set-key-roles.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Update key credits](https://unkey.com/docs/api-reference/v1/keys/update-key-credits.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Update key settings](https://unkey.com/docs/api-reference/v1/keys/update-key-settings.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Verify API key](https://unkey.com/docs/api-reference/v1/keys/verify-api-key.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Health check](https://unkey.com/docs/api-reference/v1/liveness/health-check.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [/v1/analytics.*](https://unkey.com/docs/api-reference/v1/migration/analytics.md): Migrate analytics queries from v1 to v2 for enhanced SQL-based querying - [/v1/apis.*](https://unkey.com/docs/api-reference/v1/migration/apis.md): Migrate API namespace management endpoints from v1 to v2 - [Errors](https://unkey.com/docs/api-reference/v1/migration/errors.md) - [/v1/identities.*](https://unkey.com/docs/api-reference/v1/migration/identities.md): Changes and improvements to identity endpoints from v1 to v2 - [Overview](https://unkey.com/docs/api-reference/v1/migration/index.md): Migrate from Unkey API v1 to v2 for enhanced features and improved infrastructure - [/v1/keys.*](https://unkey.com/docs/api-reference/v1/migration/keys.md): Migrate key management endpoints from v1 to v2 - [/v1/permissions.*](https://unkey.com/docs/api-reference/v1/migration/permissions.md): Migrate from key-based permission patterns to dedicated permission and role management in v2 - [/v1/ratelimits.*](https://unkey.com/docs/api-reference/v1/migration/ratelimiting.md): Migrate rate limiting and override management endpoints from v1 to v2 - [Enqueue key migration](https://unkey.com/docs/api-reference/v1/migrations/enqueue-key-migration.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Migrate keys](https://unkey.com/docs/api-reference/v1/migrations/migrate-keys.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Overview](https://unkey.com/docs/api-reference/v1/overview.md): General information about the API. - [Create permission](https://unkey.com/docs/api-reference/v1/permissions/create-permission.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Create role](https://unkey.com/docs/api-reference/v1/permissions/create-role.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Delete permission](https://unkey.com/docs/api-reference/v1/permissions/delete-permission.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Delete role](https://unkey.com/docs/api-reference/v1/permissions/delete-role.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Get permission](https://unkey.com/docs/api-reference/v1/permissions/get-permission.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Get role](https://unkey.com/docs/api-reference/v1/permissions/get-role.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [List permissions](https://unkey.com/docs/api-reference/v1/permissions/list-permissions.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [List roles](https://unkey.com/docs/api-reference/v1/permissions/list-roles.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Check rate limit](https://unkey.com/docs/api-reference/v1/ratelimits/check-rate-limit.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Delete rate limit override](https://unkey.com/docs/api-reference/v1/ratelimits/delete-rate-limit-override.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Get rate limit override](https://unkey.com/docs/api-reference/v1/ratelimits/get-rate-limit-override.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [List rate limit overrides](https://unkey.com/docs/api-reference/v1/ratelimits/list-rate-limit-overrides.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Set rate limit override](https://unkey.com/docs/api-reference/v1/ratelimits/set-rate-limit-override.md): **DEPRECATED**: This API version is deprecated. Please migrate to v2. See https://www.unkey.com/docs/api-reference/v1/migration for more information. - [Create API namespace](https://unkey.com/docs/api-reference/v2/apis/create-api-namespace.md): Create an API namespace for organizing keys by environment, service, or product. Use this to separate production from development keys, isolate different services, or manage multiple products. Each API gets a unique identifier and dedicated infrastructure for secure key operations. **Important**: API names must be unique within your workspace and cannot be changed after creation. **Required Permissions** Your root key must have one of the following permissions: - `api.*.create_api` (to create APIs in any workspace) - [Delete API namespace](https://unkey.com/docs/api-reference/v2/apis/delete-api-namespace.md): Permanently delete an API namespace and immediately invalidate all associated keys. Use this for cleaning up development environments, retiring deprecated services, or removing unused resources. All keys in the namespace are immediately marked as deleted and will fail verification with `code=NOT_FOUND`. **Important**: This operation is immediate and permanent. Verify you have the correct API ID before deletion. If delete protection is enabled, disable it first through the dashboard or API configuration. **Required Permissions** Your root key must have one of the following permissions: - `api.*.delete_api` (to delete any API) - `api..delete_api` (to delete a specific API) - [Get API namespace](https://unkey.com/docs/api-reference/v2/apis/get-api-namespace.md): Retrieve basic information about an API namespace including its ID and name. Use this to verify an API exists before performing operations, get the human-readable name when you only have the API ID, or confirm access to a specific namespace. For detailed key information, use the `listKeys` endpoint instead. **Required Permissions** Your root key must have one of the following permissions: - `api.*.read_api` (to read any API) - `api..read_api` (to read a specific API) - [List API keys](https://unkey.com/docs/api-reference/v2/apis/list-api-keys.md): Retrieve a paginated list of API keys for dashboard and administrative interfaces. Use this to build key management dashboards, filter keys by user with `externalId`, or retrieve key details for administrative purposes. Each key includes status, metadata, permissions, and usage limits. **Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys. **Required Permissions** Your root key must have one of the following permissions for basic key listing: - `api.*.read_key` (to read keys from any API) - `api..read_key` (to read keys from a specific API) Additionally, you need read access to the API itself: - `api.*.read_api` or `api..read_api` Additional permission required for decrypt functionality: - `api.*.decrypt_key` or `api..decrypt_key` - [Authentication](https://unkey.com/docs/api-reference/v2/auth.md): Securely authenticating with the Unkey API - [Error Handling](https://unkey.com/docs/api-reference/v2/errors.md): Understanding and working with API errors - [Create Identity](https://unkey.com/docs/api-reference/v2/identities/create-identity.md): Create an identity to group multiple API keys under a single entity. Identities enable shared rate limits and metadata across all associated keys. Perfect for users with multiple devices, organizations with multiple API keys, or when you need unified rate limiting across different services. **Important** Requires `identity.*.create_identity` permission - [Delete Identity](https://unkey.com/docs/api-reference/v2/identities/delete-identity.md): Permanently delete an identity. This operation cannot be undone. Use this for data cleanup, compliance requirements, or when removing entities from your system. > **Important** > Requires `identity.*.delete_identity` permission > Associated API keys remain functional but lose shared resources > External ID becomes available for reuse immediately - [Get Identity](https://unkey.com/docs/api-reference/v2/identities/get-identity.md): Retrieve an identity by external ID. Returns metadata, rate limits, and other associated data. Use this to check if an identity exists, view configurations, or build management dashboards. > **Important** > Requires `identity.*.read_identity` permission - [List Identities](https://unkey.com/docs/api-reference/v2/identities/list-identities.md): Get a paginated list of all identities in your workspace. Returns metadata and rate limit configurations. Perfect for building management dashboards, auditing configurations, or browsing your identities. > **Important** > Requires `identity.*.read_identity` permission - [Update Identity](https://unkey.com/docs/api-reference/v2/identities/update-identity.md): Update an identity's metadata and rate limits. Only specified fields are modified - others remain unchanged. Perfect for subscription changes, plan upgrades, or updating user information. Changes take effect immediately. > **Important** > Requires `identity.*.update_identity` permission > Rate limit changes propagate within 30 seconds - [Add key permissions](https://unkey.com/docs/api-reference/v2/keys/add-key-permissions.md): Add permissions to a key without affecting existing permissions. Use this for privilege upgrades, enabling new features, or plan changes that grant additional capabilities. Permissions granted through roles remain unchanged. **Important**: Changes take effect immediately with up to 30-second edge propagation. **Required Permissions** Your root key must have one of the following permissions: - `api.*.update_key` (to update keys in any API) - `api..update_key` (to update keys in a specific API) **Side Effects** Invalidates the key cache for immediate effect, and makes permissions available for verification within 30 seconds across all regions. - [Add key roles](https://unkey.com/docs/api-reference/v2/keys/add-key-roles.md): Add roles to a key without affecting existing roles or permissions. Use this for privilege upgrades, enabling new feature sets, or subscription changes that grant additional role-based capabilities. Direct permissions remain unchanged. **Important**: Changes take effect immediately with up to 30-second edge propagation. **Required Permissions** Your root key must have one of the following permissions: - `api.*.update_key` (to update keys in any API) - `api..update_key` (to update keys in a specific API) **Side Effects** Invalidates the key cache for immediate effect, and makes role assignments available for verification within 30 seconds across all regions. - [Create API key](https://unkey.com/docs/api-reference/v2/keys/create-api-key.md): Create a new API key for user authentication and authorization. Use this endpoint when users sign up, upgrade subscription tiers, or need additional keys. Keys are cryptographically secure and unique to the specified API namespace. **Important**: The key is returned only once. Store it immediately and provide it to your user, as it cannot be retrieved later. **Common use cases:** - Generate keys for new user registrations - Create additional keys for different applications - Issue keys with specific permissions or limits **Required Permissions** Your root key needs one of: - `api.*.create_key` (create keys in any API) - `api..create_key` (create keys in specific API) - [Delete API keys](https://unkey.com/docs/api-reference/v2/keys/delete-api-keys.md): Delete API keys permanently from user accounts or for cleanup purposes. Use this for user-requested key deletion, account deletion workflows, or cleaning up unused keys. Keys are immediately invalidated. Two modes: soft delete (default, preserves audit records) and permanent delete. **Important**: For temporary access control, use `updateKey` with `enabled: false` instead of deletion. **Required Permissions** Your root key must have one of the following permissions: - `api.*.delete_key` (to delete keys in any API) - `api..delete_key` (to delete keys in a specific API) - [Get API key](https://unkey.com/docs/api-reference/v2/keys/get-api-key.md): Retrieve detailed key information for dashboard interfaces and administrative purposes. Use this to build key management dashboards showing users their key details, status, permissions, and usage data. You can identify keys by `keyId` or the actual key string. **Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys. **Required Permissions** Your root key must have one of the following permissions for basic key information: - `api.*.read_key` (to read keys from any API) - `api..read_key` (to read keys from a specific API) Additional permission required for decrypt functionality: - `api.*.decrypt_key` or `api..decrypt_key` - [Get API key by hash](https://unkey.com/docs/api-reference/v2/keys/get-api-key-by-hash.md): Find out what key this is. **Required Permissions** Your root key must have one of the following permissions for basic key information: - `api.*.read_key` (to read keys from any API) - `api..read_key` (to read keys from a specific API) If your rootkey lacks permissions but the key exists, we may return a 404 status here to prevent leaking the existance of a key to unauthorized clients. If you believe that a key should exist, but receive a 404, please double check your root key has the correct permissions. - [Migrate API key(s)](https://unkey.com/docs/api-reference/v2/keys/migrate-api-keys.md): Returns HTTP 200 even on partial success; hashes that could not be migrated are listed under `data.failed`. **Required Permissions** Your root key must have one of the following permissions for basic key information: - `api.*.create_key` (to migrate keys to any API) - `api..create_key` (to migrate keys to a specific API) - [Remove key permissions](https://unkey.com/docs/api-reference/v2/keys/remove-key-permissions.md): Remove permissions from a key without affecting existing roles or other permissions. Use this for privilege downgrades, removing temporary access, or plan changes that revoke specific capabilities. Permissions granted through roles remain unchanged. **Important**: Changes take effect immediately with up to 30-second edge propagation. **Required Permissions** Your root key must have one of the following permissions: - `api.*.update_key` (to update keys in any API) - `api..update_key` (to update keys in a specific API) **Side Effects** Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions. - [Remove key roles](https://unkey.com/docs/api-reference/v2/keys/remove-key-roles.md): Remove roles from a key without affecting direct permissions or other roles. Use this for privilege downgrades, removing temporary access, or subscription changes that revoke specific role-based capabilities. Direct permissions remain unchanged. **Important**: Changes take effect immediately with up to 30-second edge propagation. **Required Permissions** Your root key must have one of the following permissions: - `api.*.update_key` (to update keys in any API) - `api..update_key` (to update keys in a specific API) **Side Effects** Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions. - [Reroll Key](https://unkey.com/docs/api-reference/v2/keys/reroll-key.md): Generate a new API key while preserving the configuration from an existing key. This operation creates a fresh key with a new token while maintaining all settings from the original key: - Permissions and roles - Custom metadata - Rate limit configurations - Identity associations - Remaining credits - Recovery settings **Key Generation:** - The system attempts to extract the prefix from the original key - If prefix extraction fails, the default API prefix is used - Key length follows the API's default byte configuration (or 16 bytes if not specified) **Original Key Handling:** - The original key will be revoked after the duration specified in `expiration` - Set `expiration` to 0 to revoke immediately - This allows for graceful key rotation with an overlap period Common use cases include: - Rotating keys for security compliance - Issuing replacement keys for compromised credentials - Creating backup keys with identical permissions **Important:** Analytics and usage metrics are tracked at both the key level AND identity level. If the original key has an identity, the new key will inherit it, allowing you to track usage across both individual keys and the overall identity. **Required Permissions** Your root key must have: - `api.*.create_key` or `api..create_key` - `api.*.encrypt_key` or `api..encrypt_key` (only when the original key is recoverable) - [Set key permissions](https://unkey.com/docs/api-reference/v2/keys/set-key-permissions.md): Replace all permissions on a key with the specified set in a single atomic operation. Use this to synchronize with external systems, reset permissions to a known state, or apply standardized permission templates. Permissions granted through roles remain unchanged. **Important**: Changes take effect immediately with up to 30-second edge propagation. **Required Permissions** Your root key must have one of the following permissions: - `api.*.update_key` (to update keys in any API) - `api..update_key` (to update keys in a specific API) **Side Effects** Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions. - [Set key roles](https://unkey.com/docs/api-reference/v2/keys/set-key-roles.md): Replace all roles on a key with the specified set in a single atomic operation. Use this to synchronize with external systems, reset roles to a known state, or apply standardized role templates. Direct permissions are never affected. **Important**: Changes take effect immediately with up to 30-second edge propagation. **Required Permissions** Your root key must have one of the following permissions: - `api.*.update_key` (to update keys in any API) - `api..update_key` (to update keys in a specific API) **Side Effects** Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions. - [Update key credits](https://unkey.com/docs/api-reference/v2/keys/update-key-credits.md): Update credit quotas in response to plan changes, billing cycles, or usage purchases. Use this for user upgrades/downgrades, monthly quota resets, credit purchases, or promotional bonuses. Supports three operations: set, increment, or decrement credits. Set to null for unlimited usage. **Important**: Setting unlimited credits automatically clears existing refill configurations. **Required Permissions** Your root key must have one of the following permissions: - `api.*.update_key` (to update keys in any API) - `api..update_key` (to update keys in a specific API) **Side Effects** Credit updates remove the key from cache immediately. Setting credits to unlimited automatically clears any existing refill settings. Changes take effect instantly but may take up to 30 seconds to propagate to all edge regions. - [Update key settings](https://unkey.com/docs/api-reference/v2/keys/update-key-settings.md): Update key properties in response to plan changes, subscription updates, or account status changes. Use this for user upgrades/downgrades, role modifications, or administrative changes. Supports partial updates - only specify fields you want to change. Set fields to null to clear them. **Important**: Permissions and roles are replaced entirely. Use dedicated add/remove endpoints for incremental changes. **Required Permissions** Your root key must have one of the following permissions: - `api.*.update_key` (to update keys in any API) - `api..update_key` (to update keys in a specific API) **Side Effects** If you specify an `externalId` that doesn't exist, a new identity will be automatically created and linked to the key. Permission updates will auto-create any permissions that don't exist in your workspace. Changes take effect immediately but may take up to 30 seconds to propagate to all edge regions due to cache invalidation. - [Verify API key](https://unkey.com/docs/api-reference/v2/keys/verify-api-key.md): Verify an API key's validity and permissions for request authentication. Use this endpoint on every incoming request to your protected resources. It checks key validity, permissions, rate limits, and usage quotas in a single call. **Important**: Always returns HTTP 200. Check the `valid` field in response data to determine if the key is authorized. **Common use cases:** - Authenticate API requests before processing - Enforce permission-based access control - Track usage and apply rate limits **Required Permissions** Your root key needs one of: - `api.*.verify_key` (verify keys in any API) - `api..verify_key` (verify keys in specific API) If you are getting a NOT_FOUND error, ensure your root key has the required verify key permissions. - [Overview](https://unkey.com/docs/api-reference/v2/overview.md): Our philosophy for building developer-friendly APIs - [Create permission](https://unkey.com/docs/api-reference/v2/permissions/create-permission.md): Create a new permission to define specific actions or capabilities in your RBAC system. Permissions can be assigned directly to API keys or included in roles. Use hierarchical naming patterns like `documents.read`, `admin.users.delete`, or `billing.invoices.create` for clear organization. **Important:** Permission names must be unique within the workspace. Once created, permissions are immediately available for assignment. **Required Permissions** Your root key must have the following permission: - `rbac.*.create_permission` - [Create role](https://unkey.com/docs/api-reference/v2/permissions/create-role.md): Create a new role to group related permissions for easier management. Roles enable consistent permission assignment across multiple API keys. **Important:** Role names must be unique within the workspace. Once created, roles are immediately available for assignment. **Required Permissions** Your root key must have the following permission: - `rbac.*.create_role` - [Delete permission](https://unkey.com/docs/api-reference/v2/permissions/delete-permission.md): Remove a permission from your workspace. This also removes the permission from all API keys and roles. **Important:** This operation cannot be undone and immediately affects all API keys and roles that had this permission assigned. **Required Permissions** Your root key must have the following permission: - `rbac.*.delete_permission` - [Delete role](https://unkey.com/docs/api-reference/v2/permissions/delete-role.md): Remove a role from your workspace. This also removes the role from all assigned API keys. **Important:** This operation cannot be undone and immediately affects all API keys that had this role assigned. **Required Permissions** Your root key must have the following permission: - `rbac.*.delete_role` - [Get permission](https://unkey.com/docs/api-reference/v2/permissions/get-permission.md): Retrieve details about a specific permission including its name, description, and metadata. **Required Permissions** Your root key must have the following permission: - `rbac.*.read_permission` - [Get role](https://unkey.com/docs/api-reference/v2/permissions/get-role.md): Retrieve details about a specific role including its assigned permissions. **Required Permissions** Your root key must have the following permission: - `rbac.*.read_role` - [List permissions](https://unkey.com/docs/api-reference/v2/permissions/list-permissions.md): Retrieve all permissions in your workspace. Results are paginated and sorted by their id. **Required Permissions** Your root key must have the following permission: - `rbac.*.read_permission` - [List roles](https://unkey.com/docs/api-reference/v2/permissions/list-roles.md): Retrieve all roles in your workspace including their assigned permissions. Results are paginated and sorted by their id. **Required Permissions** Your root key must have the following permission: - `rbac.*.read_role` - [Apply multiple rate limit checks](https://unkey.com/docs/api-reference/v2/ratelimit/apply-multiple-rate-limit-checks.md): Check and enforce multiple rate limits in a single request for any identifiers (user IDs, IP addresses, API clients, etc.). Use this to efficiently check multiple rate limits at once. Each rate limit check is independent and returns its own result with a top-level `passed` indicator showing if all checks succeeded. **Response Codes**: Rate limit checks return HTTP 200 regardless of whether limits are exceeded - check the `passed` field to see if all limits passed, or the `success` field in each individual result. 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors. **Required Permissions** Your root key must have one of the following permissions: - `ratelimit.*.limit` (to check limits in any namespace) - `ratelimit..limit` (to check limits in all specific namespaces being checked) - [Apply rate limiting](https://unkey.com/docs/api-reference/v2/ratelimit/apply-rate-limiting.md): Check and enforce rate limits for any identifier (user ID, IP address, API client, etc.). Use this for rate limiting beyond API keys - limit users by ID, IPs by address, or any custom identifier. Supports namespace organization, variable costs, and custom overrides. **Response Codes**: Rate limit checks return HTTP 200 regardless of whether the limit is exceeded - check the `success` field in the response to determine if the request should be allowed. 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors. **Required Permissions** Your root key must have one of the following permissions: - `ratelimit.*.limit` (to check limits in any namespace) - `ratelimit..limit` (to check limits in a specific namespace) - [Delete ratelimit override](https://unkey.com/docs/api-reference/v2/ratelimit/delete-ratelimit-override.md): Permanently remove a rate limit override. Affected identifiers immediately revert to the namespace default. Use this to remove temporary overrides, reset identifiers to standard limits, or clean up outdated rules. **Important:** Deletion is immediate and permanent. The override cannot be recovered and must be recreated if needed again. **Permissions:** Requires `ratelimit.*.delete_override` or `ratelimit..delete_override` - [Get ratelimit override](https://unkey.com/docs/api-reference/v2/ratelimit/get-ratelimit-override.md): Retrieve the configuration of a specific rate limit override by its identifier. Use this to inspect override configurations, audit rate limiting policies, or debug rate limiting behavior. **Important:** The identifier must match exactly as specified when creating the override, including wildcard patterns. **Permissions:** Requires `ratelimit.*.read_override` or `ratelimit..read_override` - [List ratelimit overrides](https://unkey.com/docs/api-reference/v2/ratelimit/list-ratelimit-overrides.md): Retrieve a paginated list of all rate limit overrides in a namespace. Use this to audit rate limiting policies, build admin dashboards, or manage override configurations. **Important:** Results are paginated. Use the cursor parameter to retrieve additional pages when more results are available. **Permissions:** Requires `ratelimit.*.read_override` or `ratelimit..read_override` - [Set ratelimit override](https://unkey.com/docs/api-reference/v2/ratelimit/set-ratelimit-override.md): Create or update a custom rate limit for specific identifiers, bypassing the namespace default. Use this to create premium tiers with higher limits, apply stricter limits to specific users, or implement emergency throttling. **Important:** Overrides take effect immediately and completely replace the default limit for matching identifiers. Use wildcard patterns (e.g., `premium_*`) to match multiple identifiers. **Permissions:** Requires `ratelimit.*.set_override` or `ratelimit..set_override` - [RPC-Style API](https://unkey.com/docs/api-reference/v2/rpc.md): Understanding our action-oriented API design - [Analytics](https://unkey.com/docs/apis/features/analytics.md): Per key and per API analytics - [Example](https://unkey.com/docs/apis/features/authorization/example.md): RBAC in the almost-real world - [Overview](https://unkey.com/docs/apis/features/authorization/introduction.md): Access Control with Roles and Permissions - [Roles and Permissions](https://unkey.com/docs/apis/features/authorization/roles-and-permissions.md) - [Verifying](https://unkey.com/docs/apis/features/authorization/verifying.md): Verifying permissions through the API - [Disabling Keys](https://unkey.com/docs/apis/features/enabled.md): Enable or disable a key. Disabled keys will not validate. - [Environments](https://unkey.com/docs/apis/features/environments.md): Separate your keys into live and test environments. - [Overview](https://unkey.com/docs/apis/features/ratelimiting/overview.md): How rate limiting works in unkey - [Refill](https://unkey.com/docs/apis/features/refill.md): Refill remaining key verifications on a set interval - [Usage limited keys](https://unkey.com/docs/apis/features/remaining.md): Limiting the usage of keys - [Key Revocation](https://unkey.com/docs/apis/features/revocation.md): Keys can be revoked at any time, from the API or the dashboard. - [Temporary Keys](https://unkey.com/docs/apis/features/temp-keys.md): How to create temporary API Keys in Unkey - [IP Whitelisting](https://unkey.com/docs/apis/features/whitelist.md): Unkey offers IP whitelisting to restrict requests to a specific set of IP addresses. - [Overview](https://unkey.com/docs/apis/introduction.md): Protect your public APIs - [Overview](https://unkey.com/docs/audit-log/introduction.md): Audit logs for your workspace, allowing you to see the history of all the resource requests made inside your workspace. - [Event Types](https://unkey.com/docs/audit-log/types.md): Available audit log event types - [Overview](https://unkey.com/docs/concepts/identities/overview.md): Identities are a representations of a user, an org or a machine in your application. - [Ratelimits](https://unkey.com/docs/concepts/identities/ratelimits.md): Identities can be used to share ratelimits across multiple keys - [Overview](https://unkey.com/docs/errors/overview.md): Understanding Unkey's structured error system - [assertion_failed](https://unkey.com/docs/errors/unkey/application/assertion_failed.md): A runtime assertion or invariant check failed - [invalid_input](https://unkey.com/docs/errors/unkey/application/invalid_input.md): Client provided input that failed validation - [precondition_failed](https://unkey.com/docs/errors/unkey/application/precondition_failed.md): PreconditionFailed indicates a precondition check failed. - [protected_resource](https://unkey.com/docs/errors/unkey/application/protected_resource.md): Attempt to modify a protected resource - [service_unavailable](https://unkey.com/docs/errors/unkey/application/service_unavailable.md): A service is temporarily unavailable - [unexpected_error](https://unkey.com/docs/errors/unkey/application/unexpected_error.md): An unhandled or unexpected error occurred - [key_not_found](https://unkey.com/docs/errors/unkey/authentication/key_not_found.md): The authentication key was not found - [malformed](https://unkey.com/docs/errors/unkey/authentication/malformed.md): Authentication credentials were incorrectly formatted - [missing](https://unkey.com/docs/errors/unkey/authentication/missing.md): Authentication credentials were not provided in the request - [forbidden](https://unkey.com/docs/errors/unkey/authorization/forbidden.md): The operation is not allowed - [insufficient_permissions](https://unkey.com/docs/errors/unkey/authorization/insufficient_permissions.md): The authenticated entity lacks sufficient permissions for the requested operation - [key_disabled](https://unkey.com/docs/errors/unkey/authorization/key_disabled.md): The authentication key is disabled - [workspace_disabled](https://unkey.com/docs/errors/unkey/authorization/workspace_disabled.md): The associated workspace is disabled - [analytics_connection_failed](https://unkey.com/docs/errors/unkey/data/analytics_connection_failed.md): ConnectionFailed indicates the connection to the analytics database failed. - [analytics_not_configured](https://unkey.com/docs/errors/unkey/data/analytics_not_configured.md): NotConfigured indicates analytics is not configured for the workspace. - [api_not_found](https://unkey.com/docs/errors/unkey/data/api_not_found.md): The requested API was not found - [audit_log_not_found](https://unkey.com/docs/errors/unkey/data/audit_log_not_found.md): The requested audit log was not found - [identity_already_exists](https://unkey.com/docs/errors/unkey/data/identity_already_exists.md): The requested identity already exists - [identity_not_found](https://unkey.com/docs/errors/unkey/data/identity_not_found.md): The requested identity was not found - [key_auth_not_found](https://unkey.com/docs/errors/unkey/data/key_auth_not_found.md): The requested key authentication was not found - [key_not_found](https://unkey.com/docs/errors/unkey/data/key_not_found.md): The requested key was not found - [key_space_not_found](https://unkey.com/docs/errors/unkey/data/key_space_not_found.md): NotFound indicates the requested key space was not found. - [migration_not_found](https://unkey.com/docs/errors/unkey/data/migration_not_found.md): The requested Key Migration was not found - [permission_already_exists](https://unkey.com/docs/errors/unkey/data/permission_already_exists.md): A permission with this slug already exists - [permission_not_found](https://unkey.com/docs/errors/unkey/data/permission_not_found.md): The requested permission was not found - [Ratelimit Namespace Gone](https://unkey.com/docs/errors/unkey/data/ratelimit_namespace_gone.md) - [ratelimit_namespace_not_found](https://unkey.com/docs/errors/unkey/data/ratelimit_namespace_not_found.md): The requested rate limit namespace was not found - [ratelimit_override_not_found](https://unkey.com/docs/errors/unkey/data/ratelimit_override_not_found.md): The requested rate limit override was not found - [role_already_exists](https://unkey.com/docs/errors/unkey/data/role_already_exists.md): A role with this name already exists - [role_not_found](https://unkey.com/docs/errors/unkey/data/role_not_found.md): The requested role was not found - [workspace_not_found](https://unkey.com/docs/errors/unkey/data/workspace_not_found.md): The requested workspace was not found - [client_closed_request](https://unkey.com/docs/errors/user/bad_request/client_closed_request.md): Client cancelled the request before the server could complete processing - [invalid_analytics_function](https://unkey.com/docs/errors/user/bad_request/invalid_analytics_function.md): Your query uses a function that isn't allowed for security reasons. - [invalid_analytics_query](https://unkey.com/docs/errors/user/bad_request/invalid_analytics_query.md): Your SQL query has a syntax error. - [invalid_analytics_query_type](https://unkey.com/docs/errors/user/bad_request/invalid_analytics_query_type.md): Only SELECT queries are allowed for analytics - you tried to use INSERT, UPDATE, DELETE, or another unsupported operation. - [invalid_analytics_table](https://unkey.com/docs/errors/user/bad_request/invalid_analytics_table.md): Your query references a table that doesn't exist or isn't allowed. - [permissions_query_syntax_error](https://unkey.com/docs/errors/user/bad_request/permissions_query_syntax_error.md): Invalid syntax or characters in verifyKey permissions query - [request_body_too_large](https://unkey.com/docs/errors/user/bad_request/request_body_too_large.md): Request body exceeds the maximum allowed size limit - [request_body_unreadable](https://unkey.com/docs/errors/user/bad_request/request_body_unreadable.md): Request body could not be read due to malformed request or connection issues - [request_timeout](https://unkey.com/docs/errors/user/bad_request/request_timeout.md): Request took too long to process and exceeded the server timeout - [query_quota_exceeded](https://unkey.com/docs/errors/user/too_many_requests/query_quota_exceeded.md): You've exceeded your workspace's analytics query quota for the current time window. - [query_execution_timeout](https://unkey.com/docs/errors/user/unprocessable_entity/query_execution_timeout.md): Your query took longer than the maximum execution time allowed. - [query_memory_limit_exceeded](https://unkey.com/docs/errors/user/unprocessable_entity/query_memory_limit_exceeded.md): Your query used more memory than allowed. - [query_rows_limit_exceeded](https://unkey.com/docs/errors/user/unprocessable_entity/query_rows_limit_exceeded.md): Your query tried to scan more rows than allowed. - [Welcome to Unkey](https://unkey.com/docs/introduction.md): API management redefined - [create_key](https://unkey.com/docs/libraries/ex/functions/create_key.md): Create an api key for your users - [delete_key](https://unkey.com/docs/libraries/ex/functions/delete_key.md): delete a key - [update_key](https://unkey.com/docs/libraries/ex/functions/update_key.md): Updates the configuration of a key - [update_remaining](https://unkey.com/docs/libraries/ex/functions/update_remaining.md): Updates the `remaining` value of a key - [verify_key](https://unkey.com/docs/libraries/ex/functions/verify_key.md): Verify a key - [Overview](https://unkey.com/docs/libraries/ex/overview.md): Elixir client for unkey - [unkey-go](https://unkey.com/docs/libraries/go/api.md): Unkey's API provides programmatic access for all resources within our platform. - [Overview](https://unkey.com/docs/libraries/nuxt/overview.md): Nuxt module for unkey - [unkey.py](https://unkey.com/docs/libraries/py/api.md): Unkey's API provides programmatic access for all resources within our platform. - [Overview](https://unkey.com/docs/libraries/rs/overview.md): Rust client for unkey - [Get API](https://unkey.com/docs/libraries/springboot-java/api/get.md): Retrieve information about an API - [List Keys](https://unkey.com/docs/libraries/springboot-java/api/list.md): List API keys - [Create](https://unkey.com/docs/libraries/springboot-java/functions/create.md): Create an api key for your users - [revoke](https://unkey.com/docs/libraries/springboot-java/functions/revoke.md): Revoke an api key - [Update](https://unkey.com/docs/libraries/springboot-java/functions/update.md): Update an api key - [Verify](https://unkey.com/docs/libraries/springboot-java/functions/verify.md): Verify an api key - [Overview](https://unkey.com/docs/libraries/springboot-java/overview.md): Spring Boot client for unkey - [@unkey/api](https://unkey.com/docs/libraries/ts/api.md): Unkey's API provides programmatic access for all resources within our platform. - [@unkey/cache](https://unkey.com/docs/libraries/ts/cache/overview.md): Cache middleware with types - [@unkey/hono](https://unkey.com/docs/libraries/ts/hono.md): Hono.js middleware for authenticating API keys - [@unkey/nextjs](https://unkey.com/docs/libraries/ts/nextjs.md): Next.js SDK for Unkey - [Delete Override](https://unkey.com/docs/libraries/ts/ratelimit/override/delete-override.md): Deletes an override - [Get Override](https://unkey.com/docs/libraries/ts/ratelimit/override/get-override.md): Gets a ratelimit override - [List Overrides](https://unkey.com/docs/libraries/ts/ratelimit/override/list-overrides.md): Lists all overrides - [Overview](https://unkey.com/docs/libraries/ts/ratelimit/override/overview.md): Ratelimit overrides - [Set Override](https://unkey.com/docs/libraries/ts/ratelimit/override/set-override.md): Sets an override for a ratelimit - [Ratelimit](https://unkey.com/docs/libraries/ts/ratelimit/ratelimit.md): Serverless ratelimiting - [Overview](https://unkey.com/docs/migrations/introduction.md): Migrate your API to Unkey - [Migrate keys to Unkey](https://unkey.com/docs/migrations/keys.md) - [Bun](https://unkey.com/docs/quickstart/apis/bun.md): Authentication for Bun's http server - [Express](https://unkey.com/docs/quickstart/apis/express.md): Authentication for your Express server - [Hono](https://unkey.com/docs/quickstart/apis/hono.md): API Authentication in Hono - [Next.js](https://unkey.com/docs/quickstart/apis/nextjs.md): API Authentication in Next.js - [Quickstart](https://unkey.com/docs/quickstart/identities/shared-ratelimits.md): Create your first identity and key with Unkey - [Public API Protection](https://unkey.com/docs/quickstart/onboarding/onboarding-api.md): Get started with API keys - [Ratelimiting](https://unkey.com/docs/quickstart/onboarding/onboarding-ratelimiting.md): Get started with standalone ratelimiting - [Bun](https://unkey.com/docs/quickstart/ratelimiting/bun.md): Ratelimiting endpoints with Bun's http server - [Express](https://unkey.com/docs/quickstart/ratelimiting/express.md): Ratelimiting endpoints with Express - [Hono](https://unkey.com/docs/quickstart/ratelimiting/hono.md): Ratelimiting endpoints with Hono - [Next.js](https://unkey.com/docs/quickstart/ratelimiting/nextjs.md): Ratelimiting endpoints with Next.js - [Automated Overrides](https://unkey.com/docs/ratelimiting/automated-overrides.md): Manage dynamic overrides programmatically - [Overview](https://unkey.com/docs/ratelimiting/introduction.md): Ratelimit your serverless functions. - [Consistency vs Latency](https://unkey.com/docs/ratelimiting/modes.md): Optimize for consistency or latency with different ratelimiting modes. - [Custom overrides](https://unkey.com/docs/ratelimiting/overrides.md): Override limits for identifiers without code changes. - [Delete Protection](https://unkey.com/docs/security/delete-protection.md): Prevents an resource from being deleted when enabled. - [GitHub Secret Scanning](https://unkey.com/docs/security/github-scanning.md): How Unkey protects you from leaked root keys - [Overview](https://unkey.com/docs/security/overview.md): How does Unkey work? What security measures are in place? - [Recovering Keys](https://unkey.com/docs/security/recovering-keys.md): Show keys again after they are created - [Root Keys](https://unkey.com/docs/security/root-keys.md): Learn how root keys in the Unkey API work