> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# End-to-end integration scenario

> Complete enterprise flow from signed inbound request to decision, short-lived credential, audit, and incident controls.

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:

1. Agent runtime (signs request)
2. Your backend service or gateway (verifies + enforces)
3. Clawb control plane (`/v1/verify`, `/v1/check`, control-plane APIs)
4. 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`:

<CodeGroup>
  ```bash curl theme={null}
  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>"
    }'
  ```

  ```python Python SDK theme={null}
  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")
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
    "valid": true,
    "agent_id": "agt_replace_me",
    "verified_at": "2026-02-28T00:00:00Z"
  }
  ```
</CodeGroup>

***

## 3) Request policy decision

<CodeGroup>
  ```bash curl theme={null}
  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"}
    }'
  ```

  ```python Python SDK theme={null}
  decision = control_plane.check(
      agent_id=agent_id,
      policy_id="pol_refunds_v2",
      action="refund",
      context={"amount": 249.00, "currency": "USD", "reason": "duplicate_charge"},
  )
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
    "decision": "allow",
    "trace_id": "trc_01abc",
    "reasons": []
  }
  ```
</CodeGroup>

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.

<CodeGroup>
  ```bash curl theme={null}
  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"]
    }'
  ```

  ```python Python SDK theme={null}
  mint = control_plane.identity_credentials_mint(
      agent_id=agent_id,
      provider="payments",
      audience="clawb.provider",
      ttl_seconds=120,
      one_time=True,
      scopes=["refund:execute"],
  )
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "credential": {
      "cred_id": "crd_01...",
      "token_type": "jwt",
      "expires_at": "2026-02-28T00:02:00Z"
    }
  }
  ```
</CodeGroup>

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:

<CodeGroup>
  ```bash curl theme={null}
  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"
  ```

  ```python Python SDK theme={null}
  audit = control_plane.workspace_audit_events(agent_id=agent_id, limit=20)
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "items": [
      {
        "event_id": "evt_01...",
        "action": "refund",
        "decision": "allow",
        "trace_id": "trc_01abc"
      }
    ]
  }
  ```
</CodeGroup>

***

## 6) Emergency mode (incident branch)

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

<CodeGroup>
  ```bash curl theme={null}
  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"}'
  ```

  ```python Python SDK theme={null}
  control_plane.identity_kill_switch_minting(paused=True, reason="incident INC-404")
  control_plane.identity_kill_switch_revoke_all(reason="incident INC-404")
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
    "minting_paused": true,
    "all_credentials_revoked_at": "2026-02-28T00:00:00Z"
  }
  ```
</CodeGroup>

***

## Unified branch pseudocode

<CodeGroup>
  ```python Python SDK theme={null}
  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"}
  ```
</CodeGroup>

***

## 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.

## Related docs

* [Workspace integration flow](/integration/workspace-flow)
* [Integrating `/v1/check`](/integration/check)
* [Identity credential APIs](/api-reference/identity-credentials)
* [Identity kill switch APIs](/api-reference/identity-kill-switch)
* [Workspace audit APIs](/api-reference/workspace-audit)