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

# Verification API (v1)

This page describes workspace-facing verification and feedback APIs.

## Workspace auth

<CodeGroup>
  ```http HTTP theme={null}
  # Preferred
  X-Clawb-Api-Key: ck_live_...

  # Alternative
  Authorization: Bearer ck_live_...
  ```
</CodeGroup>

## POST `/v1/verify`

Online identity verification for signed agent requests.

### Canonical format

<CodeGroup>
  ```text Text theme={null}
  METHOD
  PATH
  TIMESTAMP_MS
  NONCE
  BODY_SHA256
  ```
</CodeGroup>

<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}
  from clawb_agent_sdk import ClawbClient, WorkspaceControlPlane

  client = ClawbClient(base_url="https://api.clawb.ai/api")
  control_plane = WorkspaceControlPlane(client=client, api_key="ck_live_replace_me")

  verify = control_plane.verify(
      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>",
  )
  print(verify)
  ```
</CodeGroup>

### Response

<CodeGroup>
  ```json JSON theme={null}
  {
    "valid": true,
    "agent_id": "agt_...",
    "verification_tier": "attested",
    "risk_tier": "low",
    "revoked": false,
    "disclosure": {"disclosed": {}}
  }
  ```
</CodeGroup>

## POST `/v1/reputation/feedback`

Workspace feedback with required HMAC signature headers.

### Required headers

* `X-Clawb-Feedback-Timestamp`
* `X-Clawb-Feedback-Nonce`
* `X-Clawb-Feedback-Signature`

### Signature message

<CodeGroup>
  ```text Text theme={null}
  {timestamp_ms}
  {nonce}
  {sha256(body)}
  ```
</CodeGroup>

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST "https://api.clawb.ai/api/v1/reputation/feedback" \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Api-Key: ck_live_replace_me" \
    -H "X-Clawb-Feedback-Timestamp: 1740137855000" \
    -H "X-Clawb-Feedback-Nonce: n_123" \
    -H "X-Clawb-Feedback-Signature: <base64-hmac>" \
    -d '{
      "agent_id": "agt_replace_me",
      "verdict": "bad",
      "evidence": {"reason": "abuse_suspected"}
    }'
  ```

  ```python Python SDK theme={null}
  from clawb_agent_sdk import ClawbClient, WorkspaceControlPlane

  client = ClawbClient(base_url="https://api.clawb.ai/api")
  control_plane = WorkspaceControlPlane(client=client, api_key="ck_live_replace_me")

  feedback = control_plane.reputation_feedback(
      agent_id="agt_replace_me",
      verdict="bad",
      evidence={"reason": "abuse_suspected"},
  )
  print(feedback)
  ```
</CodeGroup>

## Related docs

* [Workspace integration flow](/integration/workspace-flow)
* [Workspace reputation feedback API](/api-reference/reputation-feedback)