Authentication & scopes

A key belongs to exactly one organization and may only do what its scopes allow.

API keys

Header: Authorization: Bearer capi_… The key identifies organization and access; the organization is inside the key, never in the call. Keys can expire and be restricted to IP addresses.

Scopes

Pattern resource:read and resource:write (write includes read), e.g. contacts:read, invoices:write. A missing scope yields 403 naming the required scopes.

http

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://www.claritos.io/developers/errors#insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient-scope",
  "requiredScopes": ["contacts:write"],
  "instance": "6f1c…"
}

Rotation

Rotating creates a new key with the same rights; the old one keeps working for 24 hours. Revocation is immediate.

Security

We store only a sha256 fingerprint. Never put keys into client code, repositories or logs. On suspicion, rotate or revoke immediately.