Documentation menu

API Keys

4 operations.

MethodEndpointDescription
GET/api/v1/api-keysList API keys
POST/api/v1/api-keysCreate an API key
GET/api/v1/api-keys/{apiKeyId}Get an API key
DELETE/api/v1/api-keys/{apiKeyId}Revoke an API key

List API keys

GET /api/v1/api-keys

Sessions must specify the organizationId query parameter. Organization-scoped credentials may omit it.

Parameters

query

NameTypeRequiredDescription
organizationIdstringoptionalSelects the organization that owns the collection. Required for session credentials. A credential scoped to one organization may omit it. Applies to List API keys.
limitintegeroptionalSets the maximum number of resources returned in this page. Applies to List API keys.
cursorstringoptionalOpaque cursor returned by the previous page; omit it to read the first page. Applies to List API keys.

Responses

StatusDescriptionBody
200Response for status 200application/json — object — apiKeys: array<object> (required); pagination: object (required)
400The request is malformed or cannot be processed.application/json — PublicApiError — error: object (required)
401Authentication failed. The Authorization header is missing, or the credential is invalid or expired.application/json — PublicApiError — error: object (required)
403Access denied. The authenticated user does not have permission to perform this action.application/json — PublicApiError — error: object (required)
404Resource not found.application/json — PublicApiError — error: object (required)
409Request conflicts with current state of the resource, including safe deployment conflict classifications.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Too many requests.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.application/json — PublicApiError — error: object (required)

Create an API key

POST /api/v1/api-keys

Requires api-keys:create. Sessions must specify organizationId. Organization-scoped credentials may omit it. API-key callers can delegate only a subset of their own grants. Rotate by creating a replacement and revoking the old key.

Parameters

query

NameTypeRequiredDescription
organizationIdstringoptionalSelects the organization that owns the collection. Required for session credentials. A credential scoped to one organization may omit it. Applies to Create an API key.

Request body

Required — Request body for: Create an API key.

application/json

NameTypeRequiredDescription
namestringoptional
grantsone of 4 typesrequired
expiresInintegeroptional
expiresAtstring | nulloptional

Responses

StatusDescriptionBody
200Response for status 200application/json — object — data: object (required)
400The request is malformed or cannot be processed.application/json — PublicApiError — error: object (required)
401Authentication failed. The Authorization header is missing, or the credential is invalid or expired.application/json — PublicApiError — error: object (required)
403Access denied. The authenticated user does not have permission to perform this action.application/json — PublicApiError — error: object (required)
404Resource not found.application/json — PublicApiError — error: object (required)
409Request conflicts with current state of the resource, including safe deployment conflict classifications.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Too many requests.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.application/json — PublicApiError — error: object (required)

Get an API key

GET /api/v1/api-keys/{apiKeyId}

Parameters

path

NameTypeRequiredDescription
apiKeyIdstringrequiredIdentifies the API key being attached or removed. Applies to Get an API key.

Responses

StatusDescriptionBody
200Response for status 200application/json — object — data: object (required)
400The request is malformed or cannot be processed.application/json — PublicApiError — error: object (required)
401Authentication failed. The Authorization header is missing, or the credential is invalid or expired.application/json — PublicApiError — error: object (required)
403Access denied. The authenticated user does not have permission to perform this action.application/json — PublicApiError — error: object (required)
404Resource not found.application/json — PublicApiError — error: object (required)
409Request conflicts with current state of the resource, including safe deployment conflict classifications.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Too many requests.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.application/json — PublicApiError — error: object (required)

Revoke an API key

DELETE /api/v1/api-keys/{apiKeyId}

Parameters

path

NameTypeRequiredDescription
apiKeyIdstringrequiredIdentifies the API key being attached or removed. Applies to Revoke an API key.

Responses

StatusDescriptionBody
200Response for status 200application/json — object — data: object (required)
400The request is malformed or cannot be processed.application/json — PublicApiError — error: object (required)
401Authentication failed. The Authorization header is missing, or the credential is invalid or expired.application/json — PublicApiError — error: object (required)
403Access denied. The authenticated user does not have permission to perform this action.application/json — PublicApiError — error: object (required)
404Resource not found.application/json — PublicApiError — error: object (required)
409Request conflicts with current state of the resource, including safe deployment conflict classifications.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Too many requests.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.application/json — PublicApiError — error: object (required)