Access Keys

GET/api/clawdbase/api-keys

POST/api/clawdbase/api-keys

PATCH/api/clawdbase/api-keys

DELETE/api/clawdbase/api-keys

Canonical scopes

Scope	Purpose
`scores:read`	Agent, Skill, Creator, X and Telegram score operations
`lineage:read`	Agent or Skill lineage
`mcp:invoke`	Reserved for a future MCP channel; MCP is planned and not yet publicly available
`billing:usage.read`	Read usage information where supported

New keys use this shared scope list. Legacy *:query scopes retain REST compatibility for their equivalent score or lineage operation, but should be rotated to the canonical model.

Create request

{
  "key_name": "production-agent-gateway",
  "environment": "production",
  "expires_at": "2026-11-15T00:00:00.000Z",
  "scopes": ["scores:read", "lineage:read"]
}

The route filters requested scopes server-side. Plan limits are 1 active key on Free, 3 on Builder, 20 on Pro and 100 on Enterprise.

Lifecycle

Create

Submit a name, environment, optional expiry and canonical scopes. The response contains key metadata and the one-time claw_live_... secret.

List

The list response returns metadata only: key ID, name, prefix, scopes, environment, active state, timestamps and safe usage fields. It never returns the secret or hash.

Rename or deactivate

Use PATCH for supported metadata and state changes. Ownership is checked server-side and updates cannot add unrecognized scopes.

Revoke

Use DELETE for permanent revocation. Existing bearer requests fail after revocation; the original secret cannot be recovered.

Create with a Console session

const response = await fetch('/api/clawdbase/api-keys', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${session.access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    key_name: 'production-agent-gateway',
    environment: 'production',
    expires_at: '2026-11-15T00:00:00.000Z',
    scopes: ['scores:read', 'lineage:read'],
  }),
})

const created = await response.json()
if (!response.ok) throw new Error(created.error)
// Store created.key immediately. It is not returned by later list requests.

Only active keys count toward the plan limit. The server enforces the limit during creation, not just by disabling the Console button. A stale browser cache therefore cannot exceed the entitlement through concurrent requests.

Naming and expiry

Names should identify workload and environment, not contain secrets. Use expirations for short-lived experiments and CI where rotation is automated. The caller must treat an expired key like a revoked credential and create a replacement through an authenticated Console session.

Incident response

If a secret appears in a log, repository or client bundle, revoke it immediately, create a replacement and inspect recent usage by key ID. Renaming a key does not rotate its secret.