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

# Quickstart

## 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](/agents/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`.

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

Reference: [Workspace integration flow](/integration/workspace-flow)

***

### 3) Check permissions with policy

<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_default",
      "action": "refund",
      "context": {"amount": 49.0, "currency": "USD", "reason": "late_delivery"}
    }'
  ```

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

Example response:

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

***

### 4) Enforce the decision in your service

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

***

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

## Next links

* [End-to-end walkthrough](/integration/end-to-end)
* [Integrating `/v1/check`](/integration/check)
* [Workspace integration flow](/integration/workspace-flow)
* [API reference](/api-reference/introduction)