Authentication - DecimalAI

All requests to the DecimalAI API authenticate with an API key. Pass it as a standard Authorization: Bearer <key> header.

curl https://api.decimal.ai/api/v1/traces \
  -H "Authorization: Bearer dai_sk_..."

Every key starts with the prefix dai_sk_. The dashboard’s session cookie auth (/api/v1/auth/me, /api/v1/auth/verify) is for the web UI only — programmatic access always uses API keys.

Key scopes

Scope controls what data a key can see. It’s set at creation time and is immutable.

Scope	What it sees	When to use
`global`	Everything in the org	SDK init for an app that spans multiple workspaces; the only scope that can create or revoke other keys
`workspace`	One workspace (specified at create time)	CI key for one team’s repo
`project`	One project under a workspace	Per-environment keys (dev / staging / prod)

A key cannot escalate to a wider scope. To widen access, create a new key.

Key permissions

Permissions control what actions a key can take, orthogonal to scope. Default is admin for backwards compatibility.

Permission	Allowed methods
`read`	`GET` only
`write`	`GET` + `POST` / `PUT` / `PATCH` (ingest, register, attach)
`admin`	All of the above + `DELETE` / destructive ops

A CI key that only ingests traces should be write. An SRE read-only on-call key should be read. Use admin only for keys that need to delete data.

Expiration

Keys can optionally expire. Pass an ISO-8601 expires_at when creating; omit for a non-expiring key (the historical default). Once expired, requests return 401 with the response body {"detail": "API key has expired"} — a distinct detail string from the revoked-key case (also 401, {"detail": "API key has been revoked"}), so callers can prompt regeneration without a generic “auth failed” branch. Both are authentication failures, so they share the 401 status with a missing or malformed key; the detail string is what distinguishes them.

Creating a key

From the dashboard

Sign in to the DecimalAI Dashboard
Go to Settings → API Keys
Click Create API Key, choose scope, permissions, and optional expiry
Copy the key — it’s shown only once and stored as a SHA-256 hash on the server

Programmatically

Requires an existing global-scoped key with admin role (only global keys can mint other keys):

curl -X POST https://api.decimal.ai/api/v1/api-keys \
  -H "Authorization: Bearer dai_sk_<your_global_admin_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "ci-staging",
    "scope": "workspace",
    "workspace_id": "ws_abc123",
    "permissions": "write",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Response (the raw key is returned once; the server keeps only the hash):

{
  "id": "key_abc123",
  "raw_key": "dai_sk_...",
  "key_prefix": "dai_sk_xxxxxxxx...",
  "label": "ci-staging",
  "scope": "workspace",
  "permissions": "write",
  "expires_at": "2027-01-01T00:00:00Z",
  "created_at": "2026-05-28T18:00:00Z"
}

A security-alert email goes to the org’s billing contact when a new key is created. If you didn’t expect it, revoke immediately.

Listing keys

curl https://api.decimal.ai/api/v1/api-keys \
  -H "Authorization: Bearer dai_sk_..."

Returns prefix, label, scope, permissions, created_at, and last_used_at for each key. Raw keys are never returned. Only global-scoped keys can list. last_used_at is updated as a fire-and-forget UPDATE on every successful auth — use it to surface stale-but-not-revoked keys for cleanup.

Rotating a key

There’s no in-place rotation. To rotate:

Create a new key

Mint a new key with the same scope and permissions as the one you’re replacing.

Roll it out

Deploy the new key to your callers (env vars, secret manager) and let them pick it up.

Revoke the old key

Revoke the old key once last_used_at on it stops advancing.

The last step is the only way to know rotation is complete — if last_used_at is still climbing, something still has the old key.

Revoking a key

curl -X DELETE https://api.decimal.ai/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer dai_sk_<your_global_admin_key>"

Revocation is immediate — in-flight requests authenticated with the revoked key will fail on the next handler invocation. Only global-scoped keys can revoke. A revoked key is soft-deleted (the row stays for audit); re-creation requires a new POST.

Security checklist

Never commit keys to source control. Use environment variables or a secret manager.
Use the narrowest scope and permissions that work. A CI key that only sends traces should be workspace/write, not global/admin.
Set expires_at on keys handed to humans. Long-lived keys without expiry should belong to automated systems with rotation procedures.
Audit last_used_at quarterly. Revoke anything that hasn’t been used in 90 days.
Lost a key? Revoke first, regenerate second. The new key won’t have the old key’s id — update any infra that pins to it.

​Key scopes

​Key permissions

​Expiration

​Creating a key

​From the dashboard

​Programmatically

​Listing keys

​Rotating a key

​Revoking a key

​Security checklist

Key scopes

Key permissions

Expiration

Creating a key

From the dashboard

Programmatically

Listing keys

Rotating a key

Revoking a key

Security checklist