API Keys API

The API Keys API lets an organization administrator manage the ak_* keys used to authenticate the Coverbase public API without contacting Coverbase support.

These endpoints accept either an admin dashboard session JWT (a user with the admin org role) or an ak_* key that carries the keys:manage scope. The scoped-key path lets headless and middleware integrations manage keys without a short-lived dashboard token. A standard integration key carries no scopes and cannot manage keys, so a compromised integration key cannot be used to mint, rotate, or revoke other keys.

All operations are org-scoped to the caller’s organization and recorded in the activity log as target_type=api_key. The Coverbase backend brokers calls to the underlying identity provider (Clerk), so customers do not need direct Clerk dashboard access. Coverbase stores only the (org, clerk_key_id) → scopes mapping, never the secret.

Key scopes

A key can carry zero or more admin scopes. A standard integration key has none and can only call ordinary /v1/* routes; granting a scope turns a key into a long-lived admin credential.

Scope	Grants
`keys:manage`	List, create, rotate, and revoke `ak_*` keys (the endpoints on this page).
`audit:read`	Read the org system audit log (`GET /v1/system_audit_log` and `GET /v1/system_audit_log/metadata`).
`banking:read`	Read full supplier bank account and tax identifiers instead of the masked last four characters.
`review:sensitive_changes`	Write bank details without waiting for review. It does not let a key approve or reject a change someone else queued.

The dashboard’s API keys page (Configuration, under Developers and integrations) offers the same scopes under Admin scopes (optional) when an admin creates a key. See API key scopes before granting the last two.

Granting scopes is a deliberate admin action and requires an admin dashboard JWT. A scoped ak_* key cannot grant scopes (not to itself and not to any other key), so a leaked key can never escalate its own access. A non-admin or scoped-key caller that supplies scopes is rejected with 403 scope_grant_forbidden, and a call made with a key that lacks the required scope returns 403 insufficient_scope.

List API keys

GET

GET /v1/api-keys

Returns every ak_* API key belonging to your org, including revoked and expired keys. Use this to audit which keys exist before rotating or revoking. Auth: admin dashboard JWT or an ak_* key with the keys:manage scope.

Example request

cURL

# Admin JWT...
curl -X GET "https://api.coverbase.app/v1/api-keys" \
  -H "Authorization: Bearer <admin-jwt>"

# ...or a key with the keys:manage scope (headless):
curl -X GET "https://api.coverbase.app/v1/api-keys" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

{
  "data": [
    {
      "id": "ak_2YkL...redacted",
      "name": "GRC pipeline (Acme)",
      "created_at": 1735689600,
      "last_used_at": 1746579000,
      "revoked": false,
      "expired": false,
      "scopes": [],
      "created_by_clerk_user_id": "user_2Zx9..."
    },
    {
      "id": "ak_7QpR...redacted",
      "name": "Headless admin (middleware)",
      "created_at": 1746000000,
      "last_used_at": 1746579500,
      "revoked": false,
      "expired": false,
      "scopes": ["keys:manage", "audit:read"],
      "created_by_clerk_user_id": "user_2Zx9..."
    }
  ]
}

Response fields

Each entry contains:

string

The key’s Clerk-side identifier (the prefix portion of ak_*). The raw secret is not returned by this endpoint; it is only available at the moment of creation or rotation.

string | null

Human-readable name set at creation time.

integer | null

Unix timestamp (seconds) when the key was created.

integer | null

Unix timestamp (seconds) of the most recent successful authentication, or null if never used.

boolean

true if the key has been revoked.

boolean

true if the key has passed its expiration.

string[]

The admin scopes granted to the key. Each value is one of "keys:manage", "audit:read", "banking:read", or "review:sensitive_changes". A standard integration key returns an empty array ([]).

string | null

The Clerk user ID of the admin who created the key.

Create an API key

POST

POST /v1/api-keys

Creates a new API key scoped to your org. The raw ak_* secret is returned once in the response body; store it immediately. Coverbase does not retain the plaintext, so a lost secret can only be replaced (rotated), not recovered. Auth: admin dashboard JWT or an ak_* key with the keys:manage scope. Note that supplying scopes requires an admin JWT (see below).

Request body

string

required

Human-readable name for the key (for example, "ServiceNow exporter"). Must be non-empty after trimming.

integer

Optional. Seconds until the key automatically expires. Omit for a non-expiring key. Recommended for keys used by short-lived integrations (for example, 31536000 for a one-year rotation policy).

string[]

Optional. Admin scopes to grant the new key: any subset of "keys:manage", "audit:read", "banking:read", and "review:sensitive_changes". Omit or pass [] to mint a standard integration key with no elevated access. Granting scopes requires an admin dashboard JWT; a non-admin or scoped-key caller that supplies a non-empty scopes array is rejected with 403 scope_grant_forbidden.

Example request

cURL

# Standard integration key (no scopes), JWT or keys:manage key:
curl -X POST "https://api.coverbase.app/v1/api-keys" \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "GRC pipeline (Acme)", "seconds_until_expiration": 31536000}'

# Scoped admin key - requires an admin JWT:
curl -X POST "https://api.coverbase.app/v1/api-keys" \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Headless admin (middleware)", "scopes": ["keys:manage", "audit:read"]}'

Example response

201 Created:

{
  "id": "ak_2YkL...redacted",
  "name": "GRC pipeline (Acme)",
  "secret": "ak_live_2YkLm3pQrStUvWxYzABCDEFGHIJKLMNOPQRSTUVWXYZabcdef",
  "created_at": 1746576000,
  "scopes": []
}

secret is the only place you will ever see the full token. If you lose it, rotate the key (which mints a new secret and revokes the old one). Treat the secret like a password.

Rotate an API key

POST

POST /v1/api-keys/{api_key_id}/rotate

Atomically rotates a key: mints a new key, then revokes the original. The new key keeps the original name with a (rotated YYYY-MM-DD) suffix, because the identity provider rejects duplicate names; a second rotation on the same day adds a counter, such as (rotated 2025-05-07 2). Use this when a secret may have been compromised, or as part of a scheduled rotation policy. The new key inherits the same scopes as the rotated key, so a scoped admin key stays scoped after rotation. If revocation of the original key fails after the new key is minted, the new key is automatically rolled back (also revoked) so the operation never leaves you with two simultaneously-active keys. Auth: admin dashboard JWT or an ak_* key with the keys:manage scope.

Path parameters

string

required

The key’s Clerk-side identifier (the prefix portion of ak_*, as returned by List API keys).

Example request

cURL

curl -X POST "https://api.coverbase.app/v1/api-keys/ak_2YkL.../rotate" \
  -H "Authorization: Bearer <admin-jwt>"

Example response

{
  "id": "ak_5ZmN...newkey",
  "name": "GRC pipeline (Acme) (rotated 2025-05-07)",
  "secret": "ak_live_5ZmN3pQrStUvWxYzABCDEFGHIJKLMNOPQRSTUVWXYZabcdef",
  "revoked_id": "ak_2YkL...redacted",
  "created_at": 1746580000,
  "scopes": []
}

Distribute the new secret to all systems that use the rotated key before removing the old one’s grace period. The old key is revoked immediately on a successful rotate, so any process still using it will start receiving 401 Unauthorized responses.

Revoke an API key

POST

POST /v1/api-keys/{api_key_id}/revoke

Revokes a key. Future requests using the revoked secret are rejected with 401 Unauthorized. The key still appears in List API keys with revoked: true for audit purposes. Revoking clears any scopes the key carried, so a revoked admin key retains no elevated access. The endpoint is idempotent: the first revocation (the active → revoked transition) is recorded in the activity log, but re-revoking an already-revoked key is a no-op that writes no additional audit entry. Auth: admin dashboard JWT or an ak_* key with the keys:manage scope.

Path parameters

string

required

The key’s Clerk-side identifier.

Request body

string

Optional. Free-form revocation reason (for example, "Employee offboarded", "Suspected leak in Sentry log"). Recorded for compliance.

Example request

cURL

curl -X POST "https://api.coverbase.app/v1/api-keys/ak_2YkL.../revoke" \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Employee offboarded"}'

Example response

200 OK: returns the same shape as List API keys, with revoked: true.

What a key can do

A key acts with the permissions of the service account role, whatever your organization’s role-based access setting. When a key calls an endpoint that needs a permission its role does not hold, the endpoint returns 403 with the code api_key_not_allowed and a message that names the permission. The default service account role does not hold org_settings, billing, audit_trail, dark_web_exposure, screening_match, rfp:approve or rfp:archive, so a key cannot use the endpoints that need them. A signed-in user calling the same endpoint is checked against their own role. The same code also means the action stays a human decision. A key never archives, unarchives, deletes or approves, whatever its role holds.

Authorization & audit

Each endpoint accepts either an admin dashboard JWT (org admin role) or an ak_* key carrying the keys:manage scope. A JWT caller without the admin role, or a key without keys:manage, is rejected.
Granting scopes is admin-only. A non-empty scopes array on create can only be supplied with an admin JWT; a scoped-key caller that passes scopes is rejected with 403 scope_grant_forbidden. A scoped key can manage keys but can never grant scopes; there is no self-propagation.
Create and rotate always write a CbActivity row (record_creation for create, field_update for rotate) against target_type=api_key. A revoke writes a field_update row only when it transitions a key from active to revoked; re-revoking an already-revoked key is an idempotent no-op and writes nothing. These rows are visible to admins in Configuration → Audit Logs (in the Integrations group).

Error responses

Status	Body	When
400	`{"detail": {"code": "invalid_name", "message": "Name cannot be empty."}}`	`name` is empty or whitespace-only on create.
401	`{"detail": "Unauthorized role."}`	A JWT whose role is not `admin`. An unknown or revoked key returns `{"detail": "Invalid or expired API key."}`.
403	`{"detail": "Not authenticated"}`	No `Authorization` header.
403	`{"detail": {"code": "insufficient_scope", "message": "..."}}`	The `ak_*` key is valid but lacks the `keys:manage` scope required for this endpoint.
403	`{"detail": {"code": "scope_grant_forbidden", "message": "..."}}`	A non-admin or scoped-key caller tried to grant `scopes` on create. Scopes can only be granted from an admin dashboard session.
403	`{"detail": {"code": "api_key_not_allowed", "message": "..."}}`	On any endpoint: the key’s role does not hold the permission the endpoint needs, or the action stays a human decision. See What a key can do.
403	`{"detail": {"code": "user_not_provisioned", "message": "..."}}`	The admin user record has no Clerk identity (rare; re-provision via support).
404	`{"detail": {"code": "api_key_not_found", "message": "API key not found."}}`	The `api_key_id` does not belong to your org or no longer exists.
502	`{"detail": {"code": "clerk_upstream_error", "message": "..."}}`	The upstream identity provider returned an error. Retry; contact support if it persists.
502	`{"detail": {"code": "clerk_missing_secret", "message": "..."}}`	On create/rotate, the identity provider returned an incomplete key (missing `id`/`secret`). The partial key is automatically revoked so none is left stranded, safe to retry.

Getting started

API reference

Data import and export

Field reference

Integration workflows

AI, agents and MCP

Key scopes

List API keys

Example request

Example response

Response fields

Create an API key

Request body

Example request

Example response

Rotate an API key

Path parameters

Example request

Example response

Revoke an API key

Path parameters

Request body

Example request

Example response

What a key can do

Authorization & audit

Error responses

​Key scopes

​List API keys

​Example request

​Example response

​Response fields

​Create an API key

​Request body

​Example request

​Example response

​Rotate an API key

​Path parameters

​Example request

​Example response

​Revoke an API key

​Path parameters

​Request body

​Example request

​Example response

​What a key can do

​Authorization & audit

​Error responses

Key scopes

List API keys

Example request

Example response

Response fields

Create an API key

Request body

Example request

Example response

Rotate an API key

Path parameters

Example request

Example response

Revoke an API key

Path parameters

Request body

Example request

Example response

What a key can do

Authorization & audit

Error responses