Docs API Keys

API Keys

Manage customer API keys: create, list, rotate, and revoke.

Use these endpoints to manage API keys for your customers. Keys are scoped to a tenant and can include custom metadata.

Create a key

Create a new API key for a customer. The key secret is only returned once.

POST /v1/api-keys

http

POST /v1/api-keys
Authorization: Bearer <project_api_key>
Content-Type: application/json

{
  "name": "Production API Key",
  "tenant_id": "tenant_123",
  "metadata": {
    "customer_email": "user@example.com",
    "plan": "pro"
  },
  "expires_at": "2026-01-01T00:00:00Z"
}

Request body

Field	Type	Required	Description
name	string	No	Human-readable name for the key
tenant_id	string	Yes	Identifier for the customer/tenant
metadata	object	No	Custom key-value pairs
expires_at	string	No	ISO 8601 expiration date

Response

201 Created

http

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "key_abc123",
  "key": "hk_live_secretkey...",
  "name": "Production API Key",
  "tenant_id": "tenant_123",
  "metadata": {
    "customer_email": "user@example.com",
    "plan": "pro"
  },
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": "2026-01-01T00:00:00Z",
  "status": "active"
}

Important: The key field contains the full secret and is only returned on create and rotate. Store it securely.

List keys

Retrieve a paginated list of API keys. Filter by tenant to get keys for a specific customer.

GET /v1/api-keys

http

GET /v1/api-keys?tenant_id=tenant_123&limit=20
Authorization: Bearer <project_api_key>

Query parameters

Parameter	Type	Description
tenant_id	string	Filter by tenant
limit	integer	Items per page (1-100, default 20)
cursor	string	Pagination cursor from previous response

Response

200 OK

http

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production API Key",
      "tenant_id": "tenant_123",
      "created_at": "2025-01-15T10:30:00Z",
      "expires_at": "2026-01-01T00:00:00Z",
      "status": "active",
      "last_used_at": "2025-01-28T14:22:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Rotate a key

Generate a new secret for an existing key. The old secret is immediately invalidated.

POST /v1/api-keys/:id/rotate

http

POST /v1/api-keys/key_abc123/rotate
Authorization: Bearer <project_api_key>

Response

200 OK

http

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "key_abc123",
  "key": "hk_live_newsecretkey...",
  "name": "Production API Key",
  "rotated_at": "2025-01-28T15:00:00Z"
}

Revoke a key

Permanently revoke an API key. This cannot be undone. The key will fail verification immediately.

DELETE /v1/api-keys/:id

http

DELETE /v1/api-keys/key_abc123
Authorization: Bearer <project_api_key>

Response

204 No Content

http

HTTP/1.1 204 No Content

Key lifecycle

active

Key is valid and can be used for verification. This is the default state after creation.

expired

Key has passed its expiration date. Verification returns valid: false.

revoked

Key was explicitly revoked via DELETE. Cannot be restored.