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 identities API
version: 2.0.0
servers:
- url: https://api.unkey.com
security:
- rootKey: []
tags:
- description: Identity management operations
name: identities
paths:
/v2/identities.createIdentity:
post:
description: '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
'
operationId: identities.createIdentity
requestBody:
content:
application/json:
examples:
basic:
summary: Simple identity
value:
externalId: user_123
withMetadata:
summary: With user data
value:
externalId: user_123
meta:
email: alice@example.com
name: Alice Smith
plan: premium
withRatelimits:
summary: With rate limits
value:
externalId: user_123
ratelimits:
- duration: 60000
limit: 1000
name: requests
schema:
$ref: '#/components/schemas/V2IdentitiesCreateIdentityRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
success:
summary: Successfully created identity
value:
meta:
requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
schema:
$ref: '#/components/schemas/V2IdentitiesCreateIdentityResponseBody'
description: ''
'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:
examples:
missingPermission:
summary: Missing required permission
value:
error:
detail: Your root key requires the 'identity.*.create_identity' permission to perform this operation
status: 403
title: Forbidden
type: forbidden
meta:
requestId: req_0uVwX4yZaAbCdEfGhIjKl
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden - Insufficient permissions (requires `identity.*.create_identity`)
'409':
content:
application/json:
examples:
identityExists:
summary: Identity already exists
value:
error:
detail: Identity with externalId "user_abc123" already exists in this workspace.
status: 409
title: Conflict
type: conflict
meta:
requestId: req_2wXyZaAbCdEfGhIjKlMnOp
schema:
$ref: '#/components/schemas/ConflictErrorResponse'
description: Conflict - Identity with this externalId already exists
'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 Identity
tags:
- identities
x-speakeasy-name-override: createIdentity
/v2/identities.deleteIdentity:
post:
description: '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
'
operationId: identities.deleteIdentity
requestBody:
content:
application/json:
examples:
basic:
summary: Delete identity
value:
identity: user_123
schema:
$ref: '#/components/schemas/V2IdentitiesDeleteIdentityRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
success:
summary: Successful deletion
value:
meta:
requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
schema:
$ref: '#/components/schemas/V2IdentitiesDeleteIdentityResponseBody'
description: Identity successfully deleted
'400':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/problem+json:
examples:
missingPermission:
summary: Missing required permission
value:
error:
detail: Your root key requires the 'identity.*.delete_identity' permission to perform this operation
status: 403
title: Forbidden
type: forbidden
meta:
requestId: req_0uVwX4yZaAbCdEfGhIjKl
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden - Insufficient permissions (requires `identity.*.delete_identity`)
'404':
content:
application/problem+json:
examples:
identityNotFound:
summary: Identity not found
value:
error:
detail: Identity with externalId "user_abc123" not found.
status: 404
title: Not Found
type: not_found
meta:
requestId: req_2wXyZaAbCdEfGhIjKlMnOp
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not Found - Identity with the specified externalId doesn't exist
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Error
security:
- rootKey: []
summary: Delete Identity
tags:
- identities
x-speakeasy-name-override: deleteIdentity
/v2/identities.getIdentity:
post:
description: '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
'
operationId: identities.getIdentity
requestBody:
content:
application/json:
examples:
basic:
summary: Get identity
value:
identity: user_123
schema:
$ref: '#/components/schemas/V2IdentitiesGetIdentityRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
success:
summary: Identity found
value:
data:
externalId: user_123
id: id_1234567890abcdef
meta:
email: alice@example.com
name: Alice Smith
plan: premium
ratelimits:
- duration: 60000
limit: 1000
name: requests
meta:
requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
schema:
$ref: '#/components/schemas/V2IdentitiesGetIdentityResponseBody'
description: Successfully retrieved the identity information
'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:
examples:
missingPermission:
summary: Missing required permission
value:
error:
detail: Your root key requires the 'identity.*.read_identity' permission to perform this operation
status: 403
title: Forbidden
type: forbidden
meta:
requestId: req_0uVwX4yZaAbCdEfGhIjKl
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden - Insufficient permissions (requires `identity.*.read_identity`)
'404':
content:
application/json:
examples:
identityNotFound:
summary: Identity not found
value:
error:
detail: Identity with externalId "user_abc123" not found.
status: 404
title: Not Found
type: not_found
meta:
requestId: req_2wXyZaAbCdEfGhIjKlMnOp
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not Found - Identity with the specified externalId doesn't exist
'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 Identity
tags:
- identities
x-speakeasy-name-override: getIdentity
/v2/identities.listIdentities:
post:
description: '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
'
operationId: identities.listIdentities
requestBody:
content:
application/json:
examples:
basic:
summary: List identities
value:
limit: 50
withCursor:
summary: With pagination cursor
value:
cursor: cursor_eyJrZXkiOiJrZXlfMTIzNCJ9
limit: 50
schema:
$ref: '#/components/schemas/V2IdentitiesListIdentitiesRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
success:
summary: Identities retrieved
value:
data:
cursor: cursor_eyJsYXN0SWQiOiJpZF8wMlpZUjNROU5QOEpNNFg4SFdTS1BXNDNKRiJ9
identities:
- externalId: user_123
id: id_01H9TQP8NP8JN3X8HWSKPW43JE
meta:
name: Alice Smith
plan: premium
ratelimits:
- duration: 60000
limit: 1000
name: requests
- externalId: user_456
id: id_02ZYR3Q9NP8JM4X8HWSKPW43JF
meta:
name: Bob Johnson
plan: basic
ratelimits:
- duration: 60000
limit: 500
name: requests
total: 247
meta:
requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
schema:
$ref: '#/components/schemas/V2IdentitiesListIdentitiesResponseBody'
description: Successfully retrieved the list of identities
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad Request - Invalid parameters
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized - Missing or invalid authentication
'403':
content:
application/json:
examples:
missingPermission:
summary: Missing required permission
value:
error:
detail: Your root key requires the 'identity.*.read_identity' permission to perform this operation
status: 403
title: Forbidden
type: forbidden
meta:
requestId: req_0uVwX4yZaAbCdEfGhIjKl
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden - Insufficient permissions (requires `identity.*.read_identity`)
'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: List Identities
tags:
- identities
x-speakeasy-name-override: listIdentities
x-speakeasy-pagination:
inputs:
- in: requestBody
name: cursor
type: cursor
outputs:
nextCursor: $.data.cursor
type: cursor
/v2/identities.updateIdentity:
post:
description: '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
'
operationId: identities.updateIdentity
requestBody:
content:
application/json:
examples:
updateMetadata:
summary: Update metadata
value:
identity: user_123
meta:
email: alice@example.com
name: Alice Smith
plan: premium
schema:
$ref: '#/components/schemas/V2IdentitiesUpdateIdentityRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2IdentitiesUpdateIdentityResponseBody'
description: Identity successfully updated
'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:
examples:
missingPermission:
summary: Missing required permission
value:
error:
detail: Your root key requires the 'identity.*.update_identity' permission to perform this operation
status: 403
title: Forbidden
type: forbidden
meta:
requestId: req_0uVwX4yZaAbCdEfGhIjKl
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden - Insufficient permissions (requires `identity.*.update_identity`)
'404':
content:
application/json:
examples:
identityNotFound:
summary: Identity not found
value:
error:
detail: Identity with externalId "user_123" not found.
status: 404
title: Not Found
type: not_found
meta:
requestId: req_2wXyZaAbCdEfGhIjKlMnOp
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not Found - Identity with the specified ID or externalId doesn't exist
'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: Update Identity
tags:
- identities
x-speakeasy-name-override: updateIdentity
components:
schemas:
ValidationError:
additionalProperties: false
properties:
location:
description: 'JSON path indicating exactly where in the request the error occurred. This helps pinpoint the problematic field or parameter. Examples include:
- ''body.name'' (field in request body)
- ''body.items[3].tags'' (nested array element)
- ''path.apiId'' (path parameter)
- ''query.limit'' (query parameter)
Use this location to identify exactly which part of your request needs correction.'
type: string
example: body.permissions[0].name
message:
description: Detailed error message explaining what validation rule was violated. This provides specific information about why the field or parameter was rejected, such as format errors, invalid values, or constraint violations.
type: string
example: Must be at least 3 characters long
fix:
description: A human-readable suggestion describing how to fix the error. This provides practical guidance on what changes would satisfy the validation requirements. Not all validation errors include fix suggestions, but when present, they offer specific remediation advice.
type: string
example: Ensure the name uses only alphanumeric characters, underscores, and hyphens
required:
- location
- message
type: object
description: Individual validation error details. Each validation error provides precise information about what failed, where it failed, and how to fix it, enabling efficient error resolution.
Meta:
type: object
required:
- requestId
properties:
requestId:
description: A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
example: req_123
type: string
additionalProperties: false
description: Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
NotFoundErrorResponse:
type: object
required:
- meta
- error
properties:
meta:
$ref: '#/components/schemas/Meta'
error:
$ref: '#/components/schemas/BaseError'
description: 'Error response when the requested resource cannot be found. This occurs when:
- The specified resource ID doesn''t exist in your workspace
- The resource has been deleted or moved
- The resource exists but is not accessible with current permissions
To resolve this error, verify the resource ID is correct and that you have access to it.'
BadRequestErrorDetails:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
properties:
errors:
description: List of individual validation errors that occurred in the request. Each error provides specific details about what failed validation, where the error occurred in the request, and suggestions for fixing it. This granular information helps developers quickly identify and resolve multiple issues in a single request without having to make repeated API calls.
items:
$ref: '#/components/schemas/ValidationError'
type: array
required:
- errors
description: Extended error details specifically for bad request (400) errors. This builds on the BaseError structure by adding an array of individual validation errors, making it easy to identify and fix multiple issues at once.
UnauthorizedErrorResponse:
type: object
required:
- meta
- error
properties:
meta:
$ref: '#/components/schemas/Meta'
error:
$ref: '#/components/schemas/BaseError'
description: 'Error response when authentication has failed or credentials are missing. This occurs when:
- No authentication token is provided in the request
- The provided token is invalid, expired, or malformed
- The token format doesn''t match expected patterns
To resolve this error, ensure you''re including a valid root key in the Authorization header.'
V2IdentitiesListIdentitiesResponseBody:
type: object
required:
- meta
- data
- pagination
properties:
meta:
$ref: '#/components/schemas/Meta'
data:
$ref: '#/components/schemas/V2IdentitiesListIdentitiesResponseData'
pagination:
$ref: '#/components/schemas/Pagination'
additionalProperties: false
V2IdentitiesListIdentitiesRequestBody:
type: object
properties:
limit:
type: integer
minimum: 1
maximum: 100
default: 100
description: The maximum number of identities to return in a single request. Use this to control response size and loading performance.
example: 50
cursor:
type: string
description: Pagination cursor from a previous response. Use this to fetch subsequent pages of results when the response contains a cursor value.
example: cursor_eyJrZXkiOiJrZXlfMTIzNCJ9
additionalProperties: false
Pagination:
type: object
properties:
cursor:
type: string
minLength: 1
maxLength: 1024
description: 'Opaque pagination token for retrieving the next page of results.
Include this exact value in the cursor field of subsequent requests.
Cursors are temporary and may expire after extended periods.
'
example: eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ==
hasMore:
type: boolean
description: 'Indicates whether additional results exist beyond this page.
When true, use the cursor to fetch the next page.
When false, you have reached the end of the result set.
'
example: true
required:
- hasMore
additionalProperties: false
description: Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
Identity:
type: object
properties:
id:
type: string
description: Identity ID
externalId:
type: string
description: External identity ID
meta:
type: object
additionalProperties: true
description: Identity metadata
x-go-type-skip-optional-pointer: true
x-go-type-skip-optional-pointer-with-omitzero: true
ratelimits:
type: array
description: Identity ratelimits
items:
$ref: '#/components/schemas/RatelimitResponse'
x-go-type-skip-optional-pointer: true
x-go-type-skip-optional-pointer-with-omitzero: true
required:
- externalId
- id
V2IdentitiesGetIdentityRequestBody:
type: object
properties:
identity:
type: string
minLength: 1
description: The ID of the identity to retrieve. This can be either the externalId (from your own system that was used during identity creation) or the identityId (the internal ID returned by the identity service).
example: user_abc123
additionalProperties: false
required:
- identity
TooManyRequestsErrorResponse:
type: object
required:
- meta
- error
properties:
meta:
$ref: '#/components/schemas/Meta'
error:
$ref: '#/components/schemas/BaseError'
description: 'Error response when the client has sent too many requests in a given time period. This occurs when you''ve exceeded a rate limit or quota for the resource you''re accessing.
The rate limit resets automatically after the time window expires. To avoid this error:
- Implement exponential backoff when retrying requests
- Cache results where appropriate to reduce request frequency
- Check the error detail message for specific quota information
- Contact support if you need a higher quota for your use case'
V2IdentitiesGetIdentityResponseBody:
type: object
required:
- meta
- data
properties:
meta:
$ref: '#/components/schemas/Meta'
data:
$ref: '#/components/schemas/Identity'
V2IdentitiesUpdateIdentityResponseBody:
type: object
required:
- data
- meta
properties:
data:
$ref: '#/components/schemas/Identity'
meta:
$ref: '#/components/schemas/Meta'
RatelimitRequest:
type: object
required:
- name
- limit
- duration
- autoApply
properties:
name:
description: 'The name of this rate limit. This name is used to identify which limit to check during key verification.
Best practices for limit names:
- Use descriptive, semantic names like ''api_requests'', ''heavy_operations'', or ''downloads''
- Be consistent with naming conventions across your application
- Create separate limits for different resource types or operation costs
- Consider using namespaced names for better organization (e.g., ''files.downloads'', ''compute.training'')
You will reference this exact name when verifying keys to check against this specific limit.'
type: string
example: api
minLength: 3
maxLength: 128
limit:
description: 'The maximum number of operations allowed within the specified time window.
When this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:
- Your infrastructure capacity and scaling limitations
- Fair usage expectations for your service
- Different tier levels for various user types
- The relative cost of the operations being limited
Higher v
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unkey/refs/heads/main/openapi/unkey-identities-api-openapi.yml