Skip to main content

​
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. 
{
  "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

import jwt from 'jsonwebtoken'
const claims = jwt.verify(token, process.env.CONTRA_PUBLIC_KEY, { algorithms: ['HS256'] })
// claims.compliance_level, claims.agent, claims.nodes…

​
Lifecycle

StateMeans
approvedToken issued. Use until exp.
expiredToken’s exp passed → call /v1/sessions/:id/refresh.
revokedUnderlying agent was revoked on-chain. Token rejects.
supersededA newer KYC was attached (tier upgrade) → token re-issued.