API Keys

API keys are application-level credentials that can be used in server-to-server workflows. Each key is scoped to an application and can optionally have an expiry date. API key management is available via the Dashboard API and these V1 endpoints.

API keys are server-side credentials. Never include API keys in client-side code, browser bundles, or mobile apps. Store them in environment variables and access only from server-side code. See Security Best Practices.

Authentication

All endpoints require a valid JWT access token with the api-keys:manage permission:

text

Authorization: Bearer {access_token}

The full API key value is shown only once — at creation time. Store it securely in your environment variables or secrets manager. It cannot be retrieved again.

List API Keys

GET /api/v1/applications/{applicationId}/api-keys

List all API keys for the application. The full key value is never returned — only the key_prefix (first 8 characters) for identification.

Response

200 OK

json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Production Server",
      "key_prefix": "sk_live_",
      "last_used_at": "2026-02-25T08:00:00Z",
      "expires_at": null,
      "revoked_at": null,
      "is_active": true,
      "created_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "CI Pipeline",
      "key_prefix": "sk_test_",
      "last_used_at": null,
      "expires_at": "2026-12-31T23:59:59Z",
      "revoked_at": "2026-02-20T10:00:00Z",
      "is_active": false,
      "created_at": "2026-01-15T00:00:00Z"
    }
  ]
}

Create API Key

POST /api/v1/applications/{applicationId}/api-keys

Create a new API key. The full plaintext key is returned only in this response.

Request Body

Field	Type	Required	Description
`name`	string	No	A descriptive name for this key (e.g., "Production Server"). Max 255 characters.
`expires_at`	string (ISO 8601)	No	Optional expiry date. Must be in the future.

Response

201 Created

json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Production Server",
    "key": "sk_live_abc123def456ghi789...",
    "key_prefix": "sk_live_",
    "expires_at": null,
    "created_at": "2026-02-25T12:00:00Z"
  },
  "warning": "Store this API key securely. It will not be shown again."
}

Get API Key

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

Retrieve details for a single API key. The full key value is not returned.

Response

200 OK

json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Production Server",
    "key_prefix": "sk_live_",
    "last_used_at": "2026-02-25T08:00:00Z",
    "expires_at": null,
    "revoked_at": null,
    "is_active": true,
    "created_at": "2026-01-01T00:00:00Z"
  }
}

Error Responses

Status	Code	Description
404	`API_KEY_NOT_FOUND`	API key not found

Revoke API Key

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

Revoke an API key. Revocation is permanent — the key will no longer authenticate. The record is retained for audit purposes.

Response

204 No Content

Error Responses

Status	Code	Description
404	`API_KEY_NOT_FOUND`	API key not found
409	`API_KEY_ALREADY_REVOKED`	Key has already been revoked

Using API Keys

API keys are credentials used in server-to-server workflows. All V1 API endpoints use JWT Bearer token authentication — API keys serve as application-level secrets that your backend can use to identify itself. Store API keys securely in environment variables or a secrets manager and never expose them in client-side code.