End-to-end integration scenario

This scenario shows a complete refund flow through the agent control plane.

Scenario and trust boundaries

Action: refund on POST /v1/refunds Systems in path:

Agent runtime (signs request)
Your backend service or gateway (verifies + enforces)
Clawb control plane (/v1/verify, /v1/check, control-plane APIs)
External payments service

Required inbound headers:

X-Clawb-Agent-Id
X-Clawb-Timestamp (milliseconds)
X-Clawb-Nonce
X-Clawb-Signature

1) Receive inbound signed request

Extract raw request fields without mutation:

method
exact path
raw body bytes
signature headers

These values are the source of truth for verification.

2) Verify identity

Use local verification or online /v1/verify:

curl -sS -X POST "https://api.clawb.ai/api/v1/verify" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: ck_live_replace_me" \
  -d '{
    "agent_id": "agt_replace_me",
    "method": "POST",
    "path": "/v1/refunds",
    "timestamp_ms": 1740137855000,
    "nonce": "2f8d8b19-5e0a-4f8b-b7d4-6dc15b1fe201",
    "body_sha256": "3adfd3eb02f15d4f4b5a9f5b2d18f8d1b6d8a7eac03f4b7a56ec8f8c2f2ff321",
    "signature_b64": "<base64-signature>"
  }'

verify_result = control_plane.verify(
    agent_id=agent_id,
    method="POST",
    path="/v1/refunds",
    timestamp_ms=timestamp_ms,
    nonce=nonce,
    body_sha256=control_plane.sha256_hex(raw_body),
    signature_b64=signature_b64,
)

if not verify_result.get("valid"):
    raise ValueError("invalid signature")

Example response:

{
  "valid": true,
  "agent_id": "agt_replace_me",
  "verified_at": "2026-02-28T00:00:00Z"
}

3) Request policy decision

curl -sS -X POST "https://api.clawb.ai/api/v1/check" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: ck_live_replace_me" \
  -d '{
    "agent_id": "agt_replace_me",
    "policy_id": "pol_refunds_v2",
    "action": "refund",
    "context": {"amount": 249.00, "currency": "USD", "reason": "duplicate_charge"}
  }'

decision = control_plane.check(
    agent_id=agent_id,
    policy_id="pol_refunds_v2",
    action="refund",
    context={"amount": 249.00, "currency": "USD", "reason": "duplicate_charge"},
)

Example response:

{
  "decision": "allow",
  "trace_id": "trc_01abc",
  "reasons": []
}

Decision branches:

allow: continue
challenge: pause and route to approval
deny: block

4) Optional: mint short-lived credential for bounded execution

Use this when the follow-on service call should be explicitly time/scoped.

curl -sS -X POST "https://api.clawb.ai/api/v1/identity/credentials/mint" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: ck_live_replace_me" \
  -d '{
    "agent_id": "agt_replace_me",
    "provider": "payments",
    "audience": "clawb.provider",
    "ttl_seconds": 120,
    "one_time": true,
    "scopes": ["refund:execute"]
  }'

mint = control_plane.identity_credentials_mint(
    agent_id=agent_id,
    provider="payments",
    audience="clawb.provider",
    ttl_seconds=120,
    one_time=True,
    scopes=["refund:execute"],
)

Example response:

{
  "ok": true,
  "credential": {
    "cred_id": "crd_01...",
    "token_type": "jwt",
    "expires_at": "2026-02-28T00:02:00Z"
  }
}

Use the returned credential only for the bounded operation.

5) Execute and record audit context

At execution time, record:

agent_id
policy_id
decision
trace_id (if present)
downstream service response status

Query recent events:

curl -sS "https://api.clawb.ai/api/v1/workspace/audit/events?agent_id=agt_replace_me&limit=20" \
  -H "X-Clawb-Api-Key: ck_live_replace_me"

audit = control_plane.workspace_audit_events(agent_id=agent_id, limit=20)

Example response:

{
  "ok": true,
  "items": [
    {
      "event_id": "evt_01...",
      "action": "refund",
      "decision": "allow",
      "trace_id": "trc_01abc"
    }
  ]
}

6) Emergency mode (incident branch)

If compromise is suspected, pause minting and revoke active credentials:

curl -sS -X POST "https://api.clawb.ai/api/v1/identity/kill-switch/minting" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: ck_live_replace_me" \
  -d '{"paused": true, "reason": "incident INC-404"}'

curl -sS -X POST "https://api.clawb.ai/api/v1/identity/kill-switch/revoke-all" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: ck_live_replace_me" \
  -d '{"reason": "incident INC-404"}'

control_plane.identity_kill_switch_minting(paused=True, reason="incident INC-404")
control_plane.identity_kill_switch_revoke_all(reason="incident INC-404")

Example response:

{
  "minting_paused": true,
  "all_credentials_revoked_at": "2026-02-28T00:00:00Z"
}

Unified branch pseudocode

if not verify_result.get("valid"):
    return {"status": 401, "error": "invalid_signature"}

decision_value = (decision.get("decision") or "").lower()
if decision_value == "deny":
    return {"status": 403, "error": "policy_denied", "trace_id": decision.get("trace_id")}
if decision_value == "challenge":
    return {"status": 403, "error": "challenge_required", "challenge": decision.get("challenge")}

# allow branch
try:
    # optional: mint bounded credential
    # execute downstream service action
    return {"status": 200, "ok": True}
except TimeoutError:
    # transport issue, not policy issue
    return {"status": 502, "error": "provider_unavailable"}

Error matrix

Symptom	Likely cause	Required action
`invalid signature` / verify fails	method/path/body/timestamp mismatch	Recompute canonical inputs from raw request bytes and exact path.
`timestamp_out_of_range`	seconds vs milliseconds or clock skew	Send ms timestamps and sync server clocks.
`policy_denied`	policy explicitly blocks action	Stop execution and return safe deny response.
`policy_challenge`	step-up condition matched	Trigger approval workflow and retry only after completion.
`429` / quota errors	rate/usage limits exceeded	Backoff + retry for safe/idempotent flows only.
`kill switch paused`	incident control active	Do not mint new credentials until incident cleared.

Verification checklist

Verify uses exact path and raw body hash.
/v1/check is called immediately before action execution.
allow, challenge, and deny branches are all tested.
Credential mint TTL/one-time behavior tested.
Audit query returns expected events.
Incident kill switch path tested in staging.

Start here

Core concepts

Build your integration

SDKs

Operate in production

API reference

End-to-end integration scenario

Scenario and trust boundaries

1) Receive inbound signed request

2) Verify identity

3) Request policy decision

4) Optional: mint short-lived credential for bounded execution

5) Execute and record audit context

6) Emergency mode (incident branch)

Unified branch pseudocode

Error matrix

Verification checklist

​Scenario and trust boundaries

​1) Receive inbound signed request

​2) Verify identity

​3) Request policy decision

​4) Optional: mint short-lived credential for bounded execution

​5) Execute and record audit context

​6) Emergency mode (incident branch)

​Unified branch pseudocode

​Error matrix

​Verification checklist

​Related docs

Scenario and trust boundaries

1) Receive inbound signed request

2) Verify identity

3) Request policy decision

4) Optional: mint short-lived credential for bounded execution

5) Execute and record audit context

6) Emergency mode (incident branch)

Unified branch pseudocode

Error matrix

Verification checklist

Related docs