Authentication

How to authenticate with the Checkrd API using JWTs and API keys.

Authentication

The Checkrd API supports two authentication methods. Which one you use depends on what you are building.

JWT (Dashboard Users)

Dashboard users authenticate via WorkOS AuthKit. After login, the API issues a JWT stored in an HttpOnly cookie. All /v1/ CRUD endpoints require this token.

bash

curl https://api.checkrd.io/v1/agents \
  -H "Authorization: Bearer eyJhbG..."

JWTs expire after 15 minutes. Use the refresh endpoint to get a new token:

bash

curl -X POST https://api.checkrd.io/auth/refresh \
  -H "Cookie: checkrd_refresh=..."

API Keys (SDKs and Agents)

API keys authenticate the Python/JS SDK when sending telemetry and receiving control signals. Create keys in the dashboard under API Keys.

Keys use a ck_live_ or ck_test_ prefix:

bash

curl -X POST https://api.checkrd.io/v1/telemetry \
  -H "Authorization: Bearer ck_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"events": [...]}'

Key visibility

The full API key is shown only once at creation. Store it securely. Only the prefix is visible in subsequent API responses.

RBAC (Role-Based Access Control)

Dashboard users have one of four roles per organization. Each API endpoint requires a minimum role:

Role	Read	Create/Update	Delete	Billing/SSO
viewer	Yes	No	No	No
member	Yes	Yes	No	No
admin	Yes	Yes	Yes	Yes
owner	Yes	Yes	Yes	Yes

Role requirements are listed on each endpoint. The API verifies roles via a live database check on every mutation.

Org Scoping

All API requests are scoped to the authenticated user's active organization. You cannot access resources belonging to another organization. To switch organizations, use the /auth/switch-org endpoint.

Overview Errors