Quickstart

1. Create an Access Key

Open Console > Developer Access > Create Access Key. Choose a name, environment and expiration. Copy the claw_live_... secret when it is displayed; Clawdbase stores only its SHA-256 hash.

2. Store the secret server-side

export CLAWDBASE_API_KEY='claw_live_replace_me'

Do not expose this value in browser code, mobile bundles, logs or a NEXT_PUBLIC_ environment variable.

3. Run an operation

curl --request POST 'https://www.clawdbase.ai/api/clawdbase/operations/run' \
  --header "Authorization: Bearer $CLAWDBASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "operation": "agent_score",
    "subject": "owner/repository",
    "channel": "api",
    "idempotency_key": "agent-owner-repository-20260815-01"
  }'

const response = await fetch('https://www.clawdbase.ai/api/clawdbase/operations/run', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CLAWDBASE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    operation: 'agent_score',
    subject: 'owner/repository',
    channel: 'api',
    idempotency_key: 'agent-owner-repository-20260815-01',
  }),
  signal: AbortSignal.timeout(50_000),
})

const body = await response.json()
if (!response.ok) throw new Error(body.error)

import os
import requests

response = requests.post(
    "https://www.clawdbase.ai/api/clawdbase/operations/run",
    headers={
        "Authorization": f"Bearer {os.environ['CLAWDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "operation": "agent_score",
        "subject": "owner/repository",
        "channel": "api",
        "idempotency_key": "agent-owner-repository-20260815-01",
    },
    timeout=50,
)

body = response.json()
if not response.ok:
    raise RuntimeError(body.get("error", "operation failed"))

The server derives the Access Key ID from the bearer secret, validates its scope, reserves usage, calls inVerus, settles the ledger and returns the updated balance.

4. Apply policy

Read the operation result as evidence. Keep your allow/review/sandbox/deny policy outside the score and record the evidence timestamp used for the decision.

TypeScript example

type OperationResponse = {
  ok: boolean
  operation: string
  channel: 'api'
  result: {
    query: { raw: string }
    scores: { trustScore: number; confidenceScore: number }
    verification_status: 'complete' | 'partial'
    mode: string
  } | null
  idempotent?: boolean
  ledger_id: string
  charge_source: 'free' | 'gifted' | 'included' | 'purchased' | 'overage'
  balance_after: Record<string, unknown> | null
  settled?: boolean
}

export async function checkAgent(subject: string, idempotencyKey: string) {
  const response = await fetch('https://www.clawdbase.ai/api/clawdbase/operations/run', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CLAWDBASE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      operation: 'agent_score',
      subject,
      channel: 'api',
      idempotency_key: idempotencyKey,
    }),
    signal: AbortSignal.timeout(50_000),
  })

  const body = await response.json()
  if (!response.ok) {
    throw new Error(`${response.status}: ${body.error ?? 'Clawdbase request failed'}`)
  }
  const result = (body as OperationResponse).result
  if (result !== null) {
    const { trustScore, confidenceScore } = result.scores
    if (!Number.isFinite(trustScore) || !Number.isFinite(confidenceScore)) {
      throw new Error('Clawdbase returned non-finite score evidence')
    }
  }
  return body as OperationResponse
}

Call this function from a server action, route handler, worker or backend service. Do not import it into a client component where the environment variable could be bundled.

Verify the charge

Open Console > Usage & Billing and locate the ledger ID returned by the operation. Confirm the operation, subject, channel, status and charge source. During a Free allowance, one successful operation consumes one call even when the operation's paid price is 10 or 20 credits.

Test failure safety

Use a controlled non-production environment to confirm that invalid input returns 400, a missing scope returns 403, exhausted balances return 402, and upstream failure returns 502 with no settled charge. Retry ambiguous 500 or 502 outcomes with the same idempotency key.

Production checklist

• Store the Access Key in the deployment secret manager.
• Set a 50-second client timeout so one bounded scoring attempt and a supported 429 retry can complete.
• Reuse the idempotency key across retries.
• Log the ledger ID and safe error code, never the bearer key.
• Handle partial or unavailable evidence in policy.
• Rotate with overlap only when the plan has spare key capacity. Free supports one active key: create the replacement only after revoking the old key, then update the workload immediately.