openapi: 3.1.0
info:
description: "Unkey's API provides programmatic access for all resources within our platform.\n\n\n### Authentication\n#\nThis API uses HTTP Bearer authentication with root keys. Most endpoints require specific permissions associated with your root key. When making requests, include your root key in the `Authorization` header:\n```\nAuthorization: Bearer unkey_xxxxxxxxxxx\n```\n\nAll responses follow a consistent envelope structure that separates operational metadata from actual data. This design provides several benefits:\n- Debugging: Every response includes a unique requestId for tracing issues\n- Consistency: Predictable response format across all endpoints\n- Extensibility: Easy to add new metadata without breaking existing integrations\n- Error Handling: Unified error format with actionable information\n\n### Success Response Format:\n```json\n{\n \"meta\": {\n \"requestId\": \"req_123456\"\n },\n \"data\": {\n // Actual response data here\n }\n}\n```\n\nThe meta object contains operational information:\n- `requestId`: Unique identifier for this request (essential for support)\n\nThe data object contains the actual response data specific to each endpoint.\n\n### Paginated Response Format:\n```json\n{\n \"meta\": {\n \"requestId\": \"req_123456\"\n },\n \"data\": [\n // Array of results\n ],\n \"pagination\": {\n \"cursor\": \"next_page_token\",\n \"hasMore\": true\n }\n}\n```\n\nThe pagination object appears on list endpoints and contains:\n- `cursor`: Token for requesting the next page\n- `hasMore`: Whether more results are available\n\n### Error Response Format:\n```json\n{\n \"meta\": {\n \"requestId\": \"req_2c9a0jf23l4k567\"\n },\n \"error\": {\n \"detail\": \"The resource you are attempting to modify is protected and cannot be changed\",\n \"status\": 403,\n \"title\": \"Forbidden\",\n \"type\": \"https://unkey.com/docs/errors/unkey/application/protected_resource\"\n }\n}\n```\n\nError responses include comprehensive diagnostic information:\n- `title`: Human-readable error summary\n- `detail`: Specific description of what went wrong\n- `status`: HTTP status code\n- `type`: Link to error documentation\n- `errors`: Array of validation errors (for 400 responses)\n\nThis structure ensures you always have the context needed to debug issues and take corrective action."
title: Unkey analytics keys API
version: 2.0.0
servers:
- url: https://api.unkey.com
security:
- rootKey: []
tags:
- description: API key management operations
name: keys
paths:
/v2/keys.addPermissions:
post:
description: '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.<api_id>.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.
'
operationId: keys.addPermissions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysAddPermissionsRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysAddPermissionsResponseBody'
description: Permissions added successfully. Returns all permissions currently assigned to the key.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Add Key Permissions
tags:
- keys
x-speakeasy-name-override: addPermissions
/v2/keys.addRoles:
post:
description: '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.<api_id>.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.
'
operationId: keys.addRoles
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysAddRolesRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysAddRolesResponseBody'
description: Roles added successfully. Returns all roles currently assigned to the key.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Add Key Roles
tags:
- keys
x-speakeasy-name-override: addRoles
/v2/keys.createKey:
post:
description: '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.<api_id>.create_key` (create keys in specific API)
'
operationId: keys.createKey
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysCreateKeyRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysCreateKeyResponseBody'
description: 'Successfully created a new API key. The response includes both the keyId (for reference in your system) and the full key string. IMPORTANT: This is the only time the complete key is available - it cannot be retrieved later. You must securely provide this key to your end user immediately.'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Create API Key
tags:
- keys
x-speakeasy-name-override: createKey
/v2/keys.deleteKey:
post:
description: '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.<api_id>.delete_key` (to delete keys in a specific API)
'
operationId: keys.deleteKey
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysDeleteKeyRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysDeleteKeyResponseBody'
description: 'Key deleted successfully. Verification fails immediately with up to 30-second edge propagation.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Delete API Keys
tags:
- keys
x-speakeasy-name-override: deleteKey
/v2/keys.getKey:
post:
description: '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.<api_id>.read_key` (to read keys from a specific API)
Additional permission required for decrypt functionality:
- `api.*.decrypt_key` or `api.<api_id>.decrypt_key`
'
operationId: keys.getKey
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysGetKeyRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysGetKeyResponseBody'
description: 'Successfully retrieved key information. When `decrypt: true`, includes plaintext key value for recoverable keys.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Get API Key
tags:
- keys
x-speakeasy-name-override: getKey
/v2/keys.migrateKeys:
post:
description: '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.<api_id>.create_key` (to migrate keys to a specific API)
'
operationId: keys.migrateKeys
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysMigrateKeysRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysMigrateKeysResponseBody'
description: Successfully migrated keys.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Migrate API Key(s)
tags:
- keys
x-speakeasy-name-override: migrateKeys
/v2/keys.removePermissions:
post:
description: '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.<api_id>.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.
'
operationId: keys.removePermissions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysRemovePermissionsRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysRemovePermissionsResponseBody'
description: Permissions removed successfully. Returns all permissions currently assigned to the key.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Remove Key Permissions
tags:
- keys
x-speakeasy-name-override: removePermissions
/v2/keys.removeRoles:
post:
description: '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.<api_id>.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.
'
operationId: keys.removeRoles
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysRemoveRolesRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysRemoveRolesResponseBody'
description: Roles removed successfully. Returns all roles currently assigned to the key.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Remove Key Roles
tags:
- keys
x-speakeasy-name-override: removeRoles
/v2/keys.rerollKey:
post:
description: "Generate a new API key while preserving the configuration from an existing key.\n\nThis operation creates a fresh key with a new token while maintaining all settings from the original key:\n- Permissions and roles\n- Custom metadata\n- Rate limit configurations\n- Identity associations\n- Remaining credits\n- Recovery settings\n\n**Key Generation:**\n- The system attempts to extract the prefix from the original key\n- If prefix extraction fails, the default API prefix is used\n- Key length follows the API's default byte configuration (or 16 bytes if not specified)\n\n**Original Key Handling:**\n- The original key will be revoked after the duration specified in `expiration`\n- Set `expiration` to 0 to revoke immediately\n- This allows for graceful key rotation with an overlap period\n\nCommon use cases include:\n- Rotating keys for security compliance\n- Issuing replacement keys for compromised credentials\n- Creating backup keys with identical permissions\n\n**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.\n\n**Required Permissions**\n\n Your root key must have:\n - `api.*.create_key` or `api.<api_id>.create_key`\n - `api.*.encrypt_key` or `api.<api_id>.encrypt_key` (only when the original key is recoverable)\n"
operationId: keys.rerollKey
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysRerollKeyRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysRerollKeyResponseBody'
description: Key rerolled successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Reroll Key
tags:
- keys
x-speakeasy-name-override: rerollKey
/v2/keys.setPermissions:
post:
description: '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.<api_id>.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.
'
operationId: keys.setPermissions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysSetPermissionsRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysSetPermissionsResponseBody'
description: Permissions set successfully. Returns all permissions currently assigned to the key.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Set Key Permissions
tags:
- keys
x-speakeasy-name-override: setPermissions
/v2/keys.setRoles:
post:
description: '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.<api_id>.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.
'
operationId: keys.setRoles
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysSetRolesRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2KeysSetRolesResponseBody'
description: Roles set successfully. Returns all roles currently assigned to the key.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Set Key Roles
tags:
- keys
x-speakeasy-name-override: setRoles
/v2/keys.updateCredits:
post:
description: '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.<api_id>.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.
# --- truncated at 32 KB (130 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unkey/refs/heads/main/openapi/unkey-keys-api-openapi.yml