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

# Token exchange API

> Exchange a signed agent assertion for a short-lived OIDC JWT after policy evaluation.

Use this endpoint when providers need cloud-compatible identity tokens minted by Clawb.

## POST `/v1/token/exchange`

### Auth

Workspace API key (same auth model as `/v1/check`).

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST https://api.clawb.ai/api/v1/token/exchange \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Api-Key: ck_live_replace_me" \
    -d '{
      "agent_id":"agt_123",
      "audience":"aws",
      "policy_id":"pol_default",
      "scopes":["s3:GetObject"],
      "agent_request":{
        "method":"POST",
        "path":"/v1/token/exchange",
        "timestamp_ms":1740137855000,
        "nonce":"n_123",
        "body_sha256":"3adfd3eb02f15d4f4b5a9f5b2d18f8d1b6d8a7eac03f4b7a56ec8f8c2f2ff321",
        "signature_b64":"<base64-signature>"
      }
    }'
  ```

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

  client = ClawbClient(base_url="https://api.clawb.ai/api")

  exchange_out = client.post(
      "/v1/token/exchange",
      headers={"X-Clawb-Api-Key": "ck_live_replace_me"},
      json={
          "agent_id": "agt_123",
          "audience": "aws",
          "policy_id": "pol_default",
          "scopes": ["s3:GetObject"],
          "agent_request": {
              "method": "POST",
              "path": "/v1/token/exchange",
              "timestamp_ms": 1740137855000,
              "nonce": "n_123",
              "body_sha256": "3adfd3eb02f15d4f4b5a9f5b2d18f8d1b6d8a7eac03f4b7a56ec8f8c2f2ff321",
              "signature_b64": "<base64-signature>",
          },
      },
  )
  print(exchange_out)
  ```
</CodeGroup>

### Success response

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "token": "<jwt>",
    "token_type": "Bearer",
    "expires_in": 900
  }
  ```
</CodeGroup>

### Error patterns

* `401 missing_api_key` when provider key is required and missing.
* `403 policy_denied` when policy evaluation blocks the request.
* `403 policy_challenge` when a challenge is required.
* `400 invalid_signature` when signature material does not verify.
* `400 replay_detected` when nonce was already used.
* `400 timestamp_out_of_range` when request timestamp is outside allowed skew.

### Security notes

* `agent_request.nonce` is replay-protected.
* `agent_request.timestamp_ms` is bounded by server skew checks.
* Returned JWT includes standard claims (`iss`, `sub`, `aud`, `exp`) plus a `clawb_claims` object.