ClariLayer Docs

Authentication

API Reference

API v1 Authentication

API-key authentication for v1 metric reads, including Agent Contract scopes, sandbox headers, limits, and revocation.

The public v1 metric API uses bearer API keys. API keys are organization-scoped, stored hashed, and checked before any metric data is read. A successful authentication result gives the route an organization boundary; metric detail and contract routes then verify that the requested metric belongs to that organization.

Header format

Send the key in the Authorization header:

Authorization: Bearer cl_0000000000000000000000000000000000000000

The key format is strict: cl_ followed by 40 lowercase hexadecimal characters. The full secret is returned once when the key is created. Store it in your own secret manager and do not place it in prompts, tickets, screenshots, or source control.

Agent Contract scopes

Current keys created through the API-key route default to the Agent Contract scope pair:

  • canonical-metric-api:read
  • definition:read

Those two scopes are the current API-key primitive for an Agent Contract: one external consumer system registered to read governed metric context.

The current create route does not create arbitrary custom scope sets. If scopes are omitted, the key receives both Agent Contract scopes. If scopes are supplied, they must be exactly the same pair.

Legacy compatibility

Older API keys may still have the legacy metrics:read scope. The compatibility layer keeps those keys working for current v1 reads.

The route-level scope requests are:

  • GET /api/v1/metrics requests metrics:read.
  • GET /api/v1/metrics/{id} requests metrics:read.
  • GET /api/v1/metrics/{id}/contract requests canonical-metric-api:read.

Compatibility is bidirectional for the live read model: current Agent Contract keys can satisfy the metrics list/detail routes, and legacy metrics:read keys can satisfy current Agent Contract read checks. New keys should use the Agent Contract scope pair.

Sandbox keys

An API key can be marked as sandbox. Sandbox keys are blocked unless the request includes this header:

X-ClariLayer-Env: sandbox

If a sandbox key omits the header or sends another value, the API returns 403 with a sandbox_key_requires_sandbox error code. Non-sandbox keys do not need the header.

Use sandbox keys for evaluation and non-production consumers where you want an explicit environment signal on every request.

Rate limits

API-key requests use a distributed per-key minute window. The default API-key rate limit is 60 requests per minute unless the key row carries a different rate_limit_per_minute.

Authentication also has a cheaper pre-verification throttle before bcrypt comparison. This protects the auth surface from repeated malformed or guessed key attempts without revealing valid prefixes.

When a request is rate-limited, the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{ "error": "Rate limit exceeded" }

The Retry-After value is expressed in seconds. Clients should back off per key rather than immediately retrying the same request.

Revocation

Workspace admins can revoke an API key through the session-authenticated API-key management route:

DELETE https://app.clarilayer.com/api/api-keys/11111111-2222-4333-8444-555555555555

That management route requires a signed-in admin or owner context. It is not authenticated with the API key being revoked.

After revocation, bearer requests using the key return:

{ "error": "API key has been revoked" }

Revocation is organization-scoped. A key ID outside the active organization is treated as not found.

Common failures

Missing header:

{ "error": "Missing Authorization header" }

Wrong scheme or shape:

{ "error": "Invalid Authorization header format. Expected: Bearer <api_key>" }

Invalid key body:

{ "error": "Invalid API key format" }

Valid key but insufficient scope:

{ "error": "Insufficient scope" }

Sandbox key without the sandbox header:

{
  "error": {
    "code": "sandbox_key_requires_sandbox",
    "message": "This API key can only be used with X-ClariLayer-Env: sandbox."
  }
}

See also