API Keys & Access Management

Qubiclo supports two authentication methods: short-lived JWT tokens (for human users) and long-lived API keys (for server-to-server integrations). API keys are scoped to specific permissions and can be rotated or revoked at any time.

Authentication Methods Compared

Method	Lifetime	Use case	Revocable
JWT (login)	900s access, 7d refresh	Human users, console sessions	Yes — logout
API Key	Long-lived (no expiry by default)	Server integrations, CI/CD, webhooks	Yes — instant

Create an API Key

POST/api-keys

curl -X POST http://localhost:8000/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claims ingestion service",
    "scopes": ["claims:write", "claims:read", "uploads:write"],
    "expires_at": null
  }'

{
  "id": "key_8f3d9c2e1a7b",
  "name": "Claims ingestion service",
  "key": "ajk_live_a8f3c2e1d9b4...",
  "scopes": ["claims:write", "claims:read", "uploads:write"],
  "created_at": "2026-05-20T10:00:00Z",
  "expires_at": null
}

The key value is shown only once at creation time. Store it securely — it cannot be retrieved again.

Using an API Key

Pass the key in the Authorization header, the same way you use a JWT token.

curl -X POST http://localhost:8000/api/v1/claims/intake \
  -H "Authorization: Bearer ajk_live_a8f3c2e1d9b4..." \
  -H "Content-Type: application/json" \
  -d '{ "claim_id": "CLM-2026-1001", ... }'

Manage API Keys

GET

/api-keys

List all API keys for the tenant (values are masked)

tenant:configure

POST

/api-keys

Create a new API key with specified scopes

tenant:configure

DELETE

/api-keys/:id

Revoke an API key — effective immediately

tenant:configure

Revoke an API Key

Revocation is immediate — inflight requests using the key will be rejected.

curl -X DELETE http://localhost:8000/api/v1/api-keys/key_8f3d9c2e1a7b \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Security Best Practices

Use the minimum scopes needed — a claims ingestion key does not need audit:read.
Rotate keys periodically or after any suspected exposure.
Store keys in a secrets manager (AWS Secrets Manager, HashiCorp Vault) — never in source code.
Set expiry dates on keys used in scripts or CI pipelines.
Monitor the audit log for unexpected usage from a key ID.

Method

Lifetime

Use case

Revocable

JWT (login)

900s access, 7d refresh

Human users, console sessions

Yes — logout

API Key

Long-lived (no expiry by default)

Server integrations, CI/CD, webhooks

Yes — instant

curl -X POST http://localhost:8000/api/v1/api-keys \ -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Claims ingestion service", "scopes": ["claims:write", "claims:read", "uploads:write"], "expires_at": null }'

{ "id": "key_8f3d9c2e1a7b", "name": "Claims ingestion service", "key": "ajk_live_a8f3c2e1d9b4...", "scopes": ["claims:write", "claims:read", "uploads:write"], "created_at": "2026-05-20T10:00:00Z", "expires_at": null }