Authentication
Overview
API keys for server-to-server calls; widget JWTs for the browser.
There are two credential types. Server-to-server calls use API keys; browser (widget) calls use short-lived widget JWTs you mint server-side — see Widget tokens.
API keys
- Prefix
sk_test_(test) orsk_live_(live). - Sent as
Authorization: Bearer sk_.... - Stored only as a SHA-256 hash — the secret is shown once at creation.
- Carry a set of scopes (below). A key can never mint another key with scopes it doesn't itself hold.
- Revocable (soft-revoke); a revoked key stops authenticating immediately.
Create, list, and revoke keys under an application:
POST /v1/applications/{id}/keys # create (secret returned once)
GET /v1/applications/{id}/keys # list (metadata only, never the secret)
DELETE /v1/applications/{id}/keys/{keyId} # revokeScopes
| Scope | Grants |
|---|---|
connections:read | read connections, records, usage |
connections:write | create connections, run records:check, mint widget tokens |
apps:admin | create/update applications, keys, credentials, webhook endpoints, subscriptions |
webhooks:write | manage webhook endpoints (where distinguished) |
usage:read | read usage/metering |
Admin mutations require apps:admin. All /applications/{id}/* mutations also
verify the application belongs to the caller's tenant (404 otherwise).
Unauthenticated endpoints
GET /healthz, GET /metrics, and GET /internal/ask require no auth and are
meant to be network-isolated in production (see Security).
They never expose secrets or tenant identifiers.