Authentication

Protected Clawdbase routes accept a bearer token in the Authorization header.

Authorization: Bearer claw_live_...

Access Key requests

Keys begin with claw_live_. The server hashes the presented secret with SHA-256, rejects missing, revoked or expired records, and resolves the owning Clawdbase user. Metered operations derive the key ID from that bearer token, so a caller cannot select a different key in the JSON body.

Console requests

The Console uses the active signed-in session for first-party requests. External integrations use a Clawdbase Access Key.

Secret handling

Create credentials only from an authenticated Console session.
Put keys in a server-side secret manager.
Use separate keys for development and production.
Set expiration and revoke keys that are no longer needed.
Never send a service-role credential to the browser.

Bearer resolution

Access Keys use the claw_live_... prefix, are stored only as hashes and carry the server-to-server scopes used by external operations. The complete secret is displayed once when the key is created.

Request example

curl --request POST 'https://www.clawdbase.ai/api/clawdbase/operations/run' \
  --header "Authorization: Bearer $CLAWDBASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "operation":"creator_score",
    "subject":"@github-handle",
    "channel":"api",
    "idempotency_key":"creator-github-handle-01"
  }'

Missing, malformed, revoked, expired or otherwise unresolved bearer credentials return 401. An authenticated request receives 403 when an explicit api_key_id is inactive, belongs to another user or lacks the required scope. For an Access Key bearer, the server derives the key ID from the secret and also returns 403 when a supplied api_key_id does not exactly match it. Do not automatically retry either response with the same credential.

Scope enforcement

Score operations require scores:read. Lineage requires lineage:read. channel: "mcp" is rejected with mcp_not_available before any scope check — MCP is planned, not a live channel, and mcp:invoke is a reserved scope no new Access Key can be issued. The optional request api_key_id cannot be used to impersonate another credential: when the bearer is an Access Key, the server derives its ID and rejects a mismatched explicit value.

Rotation procedure

Builder, Pro and Enterprise users can overlap old and new keys only while below their active-key limit. Free supports one active key, so its replacement flow is: prepare the workload change, revoke the named old key, create and capture the replacement, then update the workload immediately.

The zero-downtime overlap steps below apply only when the account has a spare active-key slot. Free accounts at their one-key limit must use the revoke-before-create flow above.

Create a replacement

Match the minimum scopes and environment of the old credential. Save the secret when it is shown.

Deploy and verify

Update the workload secret, deploy, then run one operation and confirm the new key's ledger attribution.

Revoke the old key

Deactivate or delete the prior credential only after all instances use the replacement.

Logging

Log the Access Key record ID only after authentication, never the presented secret or Authorization header. Redact account and provider tokens from errors. In client-facing messages, describe whether the credential is missing, expired, revoked or lacks scope without exposing lookup details.

On this page