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

# Identity credential APIs

> Mint, revoke, and lifecycle-manage short-lived identity credentials.

These endpoints let providers issue short-lived credentials for high-risk follow-on actions.

## POST `/v1/identity/credentials/mint`

### Auth

Workspace API key required.

### Core behavior

* Policy-gated decision before minting
* Workspace-scoped agent lookup
* TTL validation (`default=300s`, capped by server max)
* Token type: `opaque` or `jwt`

<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_01...",
      "provider": "sendgrid",
      "audience": "clawb.provider",
      "ttl_seconds": 300,
      "one_time": true,
      "scopes": ["email:send"],
      "scope_hash": "sha256:...",
      "policy_id": "pol_default",
      "token_type": "jwt"
    }'
  ```

  ```python Python SDK theme={null}
  # Mint a one-time JWT credential bounded to one operation scope.
  mint = provider.identity_credentials_mint(
      agent_id="agt_01...",
      provider="sendgrid",
      audience="clawb.provider",
      ttl_seconds=300,
      one_time=True,
      scopes=["email:send"],
      scope_hash="sha256:request-envelope-hash",
      policy_id="pol_default",
      token_type="jwt",
  )

  credential = mint["credential"]
  print("cred_id:", credential["cred_id"])
  print("expires_at:", credential["expires_at"])
  ```
</CodeGroup>

### Response shape

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "credential": {
      "cred_id": "crd_...",
      "token": "...",
      "token_type": "jwt",
      "expires_at": "2026-02-21T11:10:00Z",
      "one_time": true,
      "audience": "clawb.provider",
      "scopes": ["email:send"],
      "scope_hash": "sha256:..."
    }
  }
  ```
</CodeGroup>

### Common errors

* `401 {"error":"missing_api_key"}`
* `400 {"error":"missing_agent_id"|"invalid_ttl"|"invalid_scopes"|"invalid_token_type"}`
* `403 {"error":"minting_paused"}`
* `403 {"error":"policy_denied"|"policy_challenge"}`
* `404 {"error":"unknown_agent"|"unknown_policy"}`
* `429 {"error":"rate_limited","retry_after":...}`

## POST `/v1/identity/credentials/revoke`

Revokes one credential by token value.

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST "https://api.clawb.ai/api/v1/identity/credentials/revoke" \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Api-Key: ck_live_replace_me" \
    -d '{"token":"crd_...","reason":"suspected_exposure"}'
  ```

  ```python Python SDK theme={null}
  provider.identity_credentials_revoke(
      token="crd_...",  # token string originally returned by mint
      reason="suspected_exposure",
  )
  ```
</CodeGroup>

### Example response

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "revoked": 1,
    "reason": "suspected_exposure"
  }
  ```
</CodeGroup>

## POST `/v1/identity/credentials/revoke-by-agent`

Bulk-revokes all active credentials for one agent in this workspace.

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST "https://api.clawb.ai/api/v1/identity/credentials/revoke-by-agent" \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Api-Key: ck_live_replace_me" \
    -d '{"agent_id":"agt_01...","reason":"agent_rotated"}'
  ```

  ```python Python SDK theme={null}
  provider.identity_credentials_revoke_by_agent(
      agent_id="agt_01...",
      reason="agent_rotated",
  )
  ```
</CodeGroup>

### Example response

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "agent_id": "agt_01...",
    "revoked": 3,
    "reason": "agent_rotated"
  }
  ```
</CodeGroup>

## Junior developer checklist

1. Always pass `ttl_seconds` explicitly.
2. Use `one_time=True` for risky operations.
3. Store only metadata (`cred_id`, `expires_at`), never long-lived raw tokens.
4. Revoke aggressively during incidents.