Skip to main content
This tutorial is for teams building secure enterprise agent operations.

​
What you will build

  1. Sync workspace agent identity mappings.
  2. Query workspace-scoped audit data.
  3. Mint short-lived credentials for follow-on operations.
  4. Revoke credentials and use kill switches during incidents.
  5. Submit reputation feedback signals.

​
Prerequisites

  • Python 3.9+
  • pip install clawb-agent-sdk
  • One workspace API key (ck_live_... or ck_test_...)
  • One existing agent_id

​
Step 1: setup client objects

export CLAWB_BASE_URL="https://api.clawb.ai/api"
export CLAWB_API_KEY="ck_test_replace_me"

​
Step 2: upsert workspace mapping

curl -sS -X POST "$CLAWB_BASE_URL/v1/workspace/agents/upsert" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: $CLAWB_API_KEY" \
  -d '{
    "external_agent_key":"internal:payments-bot",
    "agent_id":"agt_01replace",
    "display_name":"Payments automation bot",
    "labels":["prod","payments"],
    "environment":"prod",
    "source":"workspace_api",
    "status":"active"
  }'
Example response: 
{
  "ok": true,
  "item": {
    "external_agent_key": "internal:payments-bot",
    "agent_id": "agt_01replace",
    "environment": "prod",
    "status": "active"
  }
}

​
Step 3: mint short-lived credential

curl -sS -X POST "$CLAWB_BASE_URL/v1/identity/credentials/mint" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: $CLAWB_API_KEY" \
  -d '{
    "agent_id":"agt_01replace",
    "provider":"sendgrid",
    "audience":"clawb.provider",
    "ttl_seconds":300,
    "one_time":true,
    "scopes":["email:send"],
    "token_type":"jwt"
  }'
Example response: 
{
  "ok": true,
  "credential": {
    "cred_id": "crd_01...",
    "token_type": "jwt",
    "expires_at": "2026-02-28T00:05:00Z",
    "one_time": true
  }
}

​
Step 4: query audit events

curl -sS "$CLAWB_BASE_URL/v1/workspace/audit/events?limit=20" \
  -H "X-Clawb-Api-Key: $CLAWB_API_KEY"
Example response: 
{
  "ok": true,
  "items": [
    {
      "event_id": "evt_01...",
      "event_type": "policy_check",
      "decision": "deny",
      "created_at": "2026-02-28T00:00:00Z"
    }
  ],
  "next_cursor": "cur_01..."
}

​
Step 5: incident response controls

curl -sS -X POST "$CLAWB_BASE_URL/v1/identity/kill-switch/minting" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: $CLAWB_API_KEY" \
  -d '{"paused":true,"reason":"incident INC-42"}'

curl -sS -X POST "$CLAWB_BASE_URL/v1/identity/kill-switch/revoke-all" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: $CLAWB_API_KEY" \
  -d '{"reason":"incident INC-42"}'

curl -sS "$CLAWB_BASE_URL/v1/identity/kill-switch/status" \
  -H "X-Clawb-Api-Key: $CLAWB_API_KEY"
Example response: 
{
  "minting_paused": true,
  "all_credentials_revoked_at": "2026-02-28T00:00:00Z"
}

​
Step 6: submit reputation feedback

curl -sS -X POST "$CLAWB_BASE_URL/v1/reputation/feedback" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: $CLAWB_API_KEY" \
  -H "X-Clawb-Feedback-Timestamp: 1740137855000" \
  -H "X-Clawb-Feedback-Nonce: n_123" \
  -H "X-Clawb-Feedback-Signature: <base64-hmac>" \
  -d '{
    "agent_id":"agt_01replace",
    "verdict":"bad",
    "evidence":{"reason":"repeated invalid_signature attempts"}
  }'
Example response: 
{
  "ok": true,
  "accepted": true,
  "received_at": "2026-02-28T00:00:00Z"
}

​
Next steps