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

# ContraToken

> The signed JWT every agent transaction carries — compliance attestations, no PII.

## What it is

The **ContraToken** is the web2-shaped output every developer gets from an `approved` session. It's an **HS256 JWT** (will be JWKS/ES256 at v1 launch) whose claims summarise the compliance decision.

```json theme={null}
{
  "iss": "contra",
  "sub": "vendor:bot_buyer_7991",
  "sid": "sess_b3f1c2a4",
  "wf":  "enhanced_kyc",
  "compliance_level": "enhanced",
  "agent": {
    "id": 42,
    "chain": 8453,
    "registry": "0x8004A169…a432"
  },
  "nodes": {
    "document_verification": "passed",
    "biometric_kyc":         "passed",
    "aml_screening":         "passed"
  },
  "iat": 1748566800,
  "exp": 1748570400
}
```

## What's *not* in it

* Name · DOB · document number · address — **never**.
* Selfie / images — **never**.
* Raw Smile result codes — **never**.

PII stays in Contra's encrypted KV. Reveal it only via the **permissioned regulator API**.

## How to verify it

<CodeGroup>
  ```typescript Node theme={null}
  import jwt from 'jsonwebtoken'
  const claims = jwt.verify(token, process.env.CONTRA_PUBLIC_KEY, { algorithms: ['HS256'] })
  // claims.compliance_level, claims.agent, claims.nodes…
  ```

  ```bash curl theme={null}
  # Or just hit the verify endpoint:
  curl -X POST https://identity.contra.id/v1/verify \
    -H "Content-Type: application/json" \
    -d "{\"token\": \"$TOKEN\"}"
  ```
</CodeGroup>

## Lifecycle

| State        | Means                                                      |
| ------------ | ---------------------------------------------------------- |
| `approved`   | Token issued. Use until `exp`.                             |
| `expired`    | Token's `exp` passed → call `/v1/sessions/:id/refresh`.    |
| `revoked`    | Underlying agent was revoked on-chain. Token rejects.      |
| `superseded` | A newer KYC was attached (tier upgrade) → token re-issued. |