API Keys

API keys are the primary authentication method for the Kraiter API. Each key is scoped to a single organisation and grants full access to that organisation's resources.

Key facts:

Keys use the format kr_ followed by a random string (e.g. kr_a1b2c3d4...).
The raw key is returned once at creation — it is never stored or retrievable again.
Each organisation can have up to 10 active keys.
Keys do not expire, but can be revoked at any time.

Important: Creating and revoking keys requires dashboard (Clerk) authentication. You cannot create or revoke keys using an API key — this prevents a leaked key from being used to generate more keys.

Create API key

POST /api/keys

Creates a new API key. Requires dashboard authentication.

Request body

Field	Type	Required	Description
`name`	string	Yes	A label for the key (1–64 characters).

Response

Returns 201 Created with the new key details. Copy the rawKey immediately — it cannot be retrieved again.

{
  "keyId": "key_01H9...",
  "name": "Production",
  "keyPrefix": "kr_a1b2",
  "rawKey": "kr_a1b2c3d4e5f6...",
  "createdAt": "2025-09-15T10:30:00.000Z"
}

Field	Type	Description
`keyId`	string	Unique identifier for the key (used for revocation).
`name`	string	The label you provided.
`keyPrefix`	string	The first characters of the key, for identification in the dashboard.
`rawKey`	string	The full API key. Store it securely — this is the only time it is returned.
`createdAt`	string	ISO 8601 timestamp.

Errors

Code	Description
`VALIDATION_ERROR`	Missing or invalid `name`, or the organisation already has 10 active keys.
`FORBIDDEN`	The request was not made via dashboard authentication.

Examples

curl -X POST https://api.kraiter.com/api/keys \
  -H "Authorization: Bearer CLERK_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production" }'

List API keys

GET /api/keys

Returns all API keys for the current organisation. The response includes metadata only — hashes and raw keys are never returned.

Response

{
  "items": [
    {
      "keyId": "key_01H9...",
      "tenantId": "ten_01H8...",
      "name": "Production",
      "keyPrefix": "kr_a1b2",
      "status": "active",
      "createdAt": "2025-09-15T10:30:00.000Z"
    }
  ]
}

Field	Type	Description
`keyId`	string	Unique key identifier.
`tenantId`	string	The organisation the key belongs to.
`name`	string	The label assigned at creation.
`keyPrefix`	string	First characters of the key for identification.
`status`	string	`active` or `revoked`.
`createdAt`	string	ISO 8601 timestamp.

Examples

curl https://api.kraiter.com/api/keys \
  -H "Authorization: Bearer YOUR_API_KEY"

Revoke API key

DELETE /api/keys/:keyId

Permanently revokes an API key. Requires dashboard authentication. Once revoked, any request using this key will receive a 401 Unauthorised response.

Path parameters

Parameter	Type	Description
`keyId`	string	The ID of the key to revoke.

Response

Returns 204 No Content on success.

Errors

Code	Description
`NOT_FOUND`	No key with this ID exists for the current organisation.
`FORBIDDEN`	The request was not made via dashboard authentication.

Examples

curl -X DELETE https://api.kraiter.com/api/keys/key_01H9... \
  -H "Authorization: Bearer CLERK_SESSION_TOKEN"

Best practices

Rotate keys periodically. Create a new key, update your systems, then revoke the old one.
Use descriptive names. Label keys by environment or service (e.g. "Production API", "Staging CI") so you know which to revoke if compromised.
Never commit keys to source control. Use environment variables or a secrets manager.
Restrict dashboard access. Since key creation requires dashboard auth, limiting who can access the dashboard limits who can generate keys.

API Keys

On this page