Skip to main content

​
What you’re building

You’re integrating Clawb as the workspace control plane for an enterprise fleet of agents. Your gateway/backend will:
  • register and attest agent identities at scale
  • verify inbound signed agent requests
  • check agent permissions immediately before execution with POST /v1/check
Clawb returns a decision:
  • allow → proceed
  • challenge → require extra proof
  • deny → block

​
Prerequisites

You should have:
  • Base URL: https://api.clawb.ai/api
  • Workspace API key: ck_live_...
  • Agent identity material (agent_id, keypair, attested status)
  • A backend service or gateway endpoint where agent requests arrive
  • Stable server clock (timestamps must be milliseconds)

​
Fast path architecture (single inbound request)

  1. Agent sends a signed request to your backend.
  2. Your backend verifies and normalizes the agent identity (/v1/verify or local signature verification).
  3. Your backend requests a permission decision (/v1/check).
  4. Your backend enforces allow | challenge | deny.
  5. Your backend logs trace_id and decision metadata.

​
Step-by-step implementation

​
1) Register and attest agent identities

An agent is an identity with an agent_id and one or more keys. Register and attest each agent once, then reuse the identity on every request. For large fleets, run this as part of your agent provisioning pipeline. See Attestation for full language-specific examples.

​
2) Verify inbound agent request identity

You can:
  • verify signatures locally (recommended for low latency), or
  • call online verification via /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>"
  }'
Example response: 
{
  "valid": true,
  "agent_id": "agt_replace_me",
  "verified_at": "2026-02-28T00:00:00Z"
}
Reference: Workspace integration flow

​
3) Check permissions with policy

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_default",
    "action": "refund",
    "context": {"amount": 49.0, "currency": "USD", "reason": "late_delivery"}
  }'
Example response: 
{
  "decision": "allow",
  "trace_id": "trc_01abc",
  "reasons": []
}

​
4) Enforce the decision in your service

decision_value = (decision.get("decision") or "").lower()

if decision_value == "allow":
    # Execute business action.
    pass
elif decision_value == "challenge":
    # Return challenge-required response and trigger step-up/approval path.
    pass
else:
    # Deny safely.
    pass

​
5) Record trace and audit data

At minimum, log:
  • agent_id
  • policy_id
  • action
  • decision
  • trace_id (if present)
  • reasons / reason_codes (if present)
This makes incident triage and policy tuning much faster.

​
Failure handling and retries

  • Invalid identity (401 or valid=false): stop immediately, do not run action.
  • Policy challenge / deny (403): treat as expected business control outcomes, not transport failures.
  • Rate/Quota (429): retry with backoff for non-destructive flows only.
  • Transient server/network failures (5xx / timeout):
    • prefer fail-closed for high-risk actions,
    • allow controlled retry for idempotent operations.
If your action is sensitive and non-idempotent, never “retry execute” unless you have deduplication/idempotency keys in place.

​
Production readiness checklist

  • Signature verification enabled on all sensitive agent endpoints.
  • Timestamp validation uses milliseconds and clock skew limits.
  • /v1/check wired immediately before execution.
  • All three branches (allow, challenge, deny) tested.
  • Decision + trace metadata logged and queryable.
  • Agent registration/attestation flow automated for new agents.
  • Incident runbook includes kill switch and credential revocation paths.

​
Common pitfalls

  • If you never attest, the agent may remain pending and policies may return challenge.
  • If your service doesn’t verify signatures, any caller can pretend to be an agent by guessing an agent_id.
  • Timestamp seconds vs milliseconds mismatch causes verification failures.
  • Path/body-hash mismatches cause signature verification failures.