Skip to main content
The Kordless API uses bearer-token authentication. Your API key is the session — there is no OAuth flow, no token refresh, and no Clerk dependency on the API surface.

​
Key format

Every API key is a secret string with an environment prefix: The prefix is not cosmetic — it is the first check the API performs. A Test key cannot address Live data because the environment is encoded in the key itself, before any database lookup.
Never expose a Live key in client-side code, public repositories, or logs. Live keys can produce real quotes and create real commitments.

​
Sending the key

Pass the key as a bearer token in the Authorization header:

​
Key storage

Only the SHA-256 hash of a key is stored. The plaintext secret is returned exactly once — at mint time or at rotation. A display prefix (for example, sk_test_a1b2c3) is stored so you can recognize the key in the Developers page without the secret.

​
Scopes

Each key has a set of scopes that limit which operations it can perform. When you mint a key, choose the minimum set of scopes your integration needs. If a key lacks the required scope for an operation, the API returns a 403 with code: "insufficient_scope".

​
Key lifecycle

​
Minting

Only an organization admin can mint API keys. Minting requires the api_access feature on the account.

​
Rotation

Rolling a key creates a new key with the same name, environment, and scopes, and schedules the old key for revocation after a grace period:
  • Default grace: 24 hours.
  • Maximum grace: 168 hours (7 days).
  • Immediate rotation: Set grace to 0 hours.
During the grace period, both keys work. The old key’s revoked_at is set to a future timestamp; the API accepts it until that instant passes. After expiry, the old key returns 401 with code: "revoked_api_key".

​
Revocation

Revoking a key kills it immediately. The revocation timestamp is preserved — if the key was already revoked, the original timestamp is kept.

​
Status

​
Checking key liveness

Use GET /v1/accounts/current to verify a key and inspect its environment and scopes:
This endpoint requires no specific scope — any valid key can call it. Use it as a health check in your integration.

​
Rate limiting

API requests are rate-limited per account and environment, not per key. Sibling keys on the same account and environment share one quota. The default limit is 600 requests per minute. When the limit is exceeded, the API returns 429 with a retry-after header.

​
What authentication does not do

  • Authentication does not authorize Book authoring or verification. Those are workspace operations.
  • Authentication does not manage billing or plans. Those are admin operations.
  • A key’s scopes do not override the Book’s autonomy mode. If the Book is in approval-first mode, every produced quote is held for owner review regardless of the API key’s scopes.