API Keys

Create, list, revoke, and delete API keys for SDK authentication.

API Keys

API keys authenticate the Checkrd SDK when sending telemetry and receiving control signals. Keys use a ck_live_ or ck_test_ prefix and are scoped to one of three permission models.

The API Key Object

json

{
  "id": "01916b00-1234-5678-9abc-def012345678",
  "org_id": "01916a3e-0000-0000-0000-000000000000",
  "name": "production",
  "description": "Used by the sales-agent SDK in prod",
  "key_prefix": "ck_live_abc1",
  "scope": { "kind": "all" },
  "last_used_at": "2026-04-12T09:15:00Z",
  "expires_at": null,
  "revoked_at": null,
  "created_at": "2026-04-10T14:30:00Z"
}

Field	Type	Description
`id`	UUID	Unique identifier.
`name`	string	Display name.
`key_prefix`	string	First characters of the key. The full key is only shown at creation.
`scope`	object	Permission scope. See Scope shapes below.
`last_used_at`	ISO 8601 or null	Last time the key was used to authenticate.
`expires_at`	ISO 8601 or null	Expiration timestamp, or null for no expiration.
`revoked_at`	ISO 8601 or null	Revocation timestamp, or null if active.

Scope shapes

The scope object is a tagged union with three forms.

Full access (read + write everywhere):

json

{ "kind": "all" }

Read-only (every GET endpoint succeeds; mutations return 403):

json

{ "kind": "read_only" }

Per-resource matrix (resources not listed are denied):

json

{
  "kind": "restricted",
  "resources": {
    "agents": "write",
    "policies": "read",
    "events": "read"
  }
}

Kind	Effect
`all`	Read + write across the workspace. Equivalent to `--scope full` in the CLI.
`read_only`	GET endpoints only; mutations return `403`. Equivalent to `--scope read-only` in the CLI.
`restricted`	Per-resource matrix. Each resource maps to `read` or `write`. Resources not listed are denied.

Create an API Key

POST /v1/keys

Auth: JWT (admin+)

Parameter	Type	Required	Description
`name`	string	Yes	Display name for the key.
`description`	string	No	Optional description.
`scope`	object	Yes	One of the three scope shapes documented above.

bash

curl -X POST https://api.checkrd.io/v1/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production",
    "description": "Sales agent SDK",
    "scope": { "kind": "all" }
  }'

Response 200 OK

json

{
  "id": "01916b00-1234-5678-9abc-def012345678",
  "name": "production",
  "key": "ck_live_abc123def456ghi789jkl012mno345",
  "key_prefix": "ck_live_abc1"
}

Store the key now

The key field contains the full API key and is only returned once. It cannot be retrieved again. Copy it immediately.

Subject to plan tier key limits (Free: 2, Team: 20, Enterprise: unlimited).

List API Keys

GET /v1/keys

Auth: JWT (viewer+)

Parameter	Type	Required	Description
`limit`	integer	No	Results per page (default 20, max 100).
`cursor`	string	No	Opaque pagination cursor.

bash

curl https://api.checkrd.io/v1/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 200 OK: paginated list. The full key value is never included in list responses.

Revoke an API Key

Revoking marks the key as inactive. Subsequent requests using it return 401. The row is preserved so audit-log references remain valid.

POST /v1/keys/:key_id/revoke

Auth: JWT (admin+)

bash

curl -X POST https://api.checkrd.io/v1/keys/01916b00-1234-.../revoke \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 200 OK

json

{ "success": true }

Delete an API Key

Permanently removes the key row. Only allowed once the key has been revoked. Returns 409 with code api_key_not_revoked if the key is still active.

DELETE /v1/keys/:key_id

Auth: JWT (admin+)

bash

curl -X DELETE https://api.checkrd.io/v1/keys/01916b00-1234-... \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 200 OK

json

{ "success": true }

Agents Policies