POST /verify-token

Verify a cryptographic receipt from a previous age assessment and decode the original verdict payload.

Endpoint

Every response from POST /v1/assurance/assess-age includes a verification_token — an HMAC-SHA256 signed cryptographic receipt you store in your own logs. This endpoint verifies the token's signature and returns the decoded receipt payload.

Free utility — this endpoint does not count against your monthly quota and incurs no billing charges.

Request Body

Response

Valid Token (200 OK)

When the token signature is valid:

{
  "valid": true,
  "payload": {
    "v": 1,
    "ts": "2026-02-07T14:30:00.000Z",
    "verdict": "OVERRIDE",
    "assessed_bracket": "under-13",
    "os_bracket": "18-plus",
    "confidence": 0.96,
    "overridden": true,
    "evidence": [
      "low_touch_precision",
      "high_motor_precision_delta",
      "signal_override_active",
      "rule_source:1798.501.b.3.B"
    ]
  }
}

Invalid Token (200 OK)

When the token signature is invalid or the token is malformed:

{
  "valid": false,
  "payload": null
}

Response Fields

Validation Error (400 Bad Request)

Returned when the request body is missing or verification_token is empty:

{
  "statusCode": 400,
  "message": ["verification_token must be a non-empty string"],
  "error": "Bad Request"
}

Authentication Error (401 Unauthorized)

This endpoint requires an API key, like all A3 endpoints:

{
  "statusCode": 401,
  "message": "Unauthorized"
}

When to Use This Endpoint

Dispute Resolution

If a user or regulator disputes an age determination:

1. Retrieve the verification_token from your audit logs.
2. Send it to this endpoint.
3. The decoded payload proves exactly what was assessed, when, and why — without A3 having stored any user data.

Audit Workflows

Compliance teams can batch-verify tokens during periodic audits to confirm that stored receipts are authentic and have not been tampered with.

Debug & Inspect

During development, use this endpoint to inspect what's inside a verification token without manually decoding the base64url payload.

Code Examples

curl -X POST https://api.a3api.io/v1/assurance/verify-token \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "verification_token": "eyJ2IjoxLCJ0cyI6IjIwMjYtMDItMDdUMTQ6MzA6MDBaIiwidmVyZGljdCI6Ik9WRVJSSURFIn0.abc123signature"
}'

Full Assess-then-Verify Round Trip

import { A3Client } from '@a3api/node';

const client = new A3Client({ apiKey: process.env.A3_API_KEY! });

// 1. Assess age
const assessment = await client.assessAge({
os_signal: '18-plus',
user_country_code: 'US',
});

// 2. Store the token in your audit log
await saveToAuditLog(userId, assessment.verification_token);

// 3. Later — verify the token during a dispute
const verification = await client.verifyToken({
verification_token: assessment.verification_token,
});

console.log(verification.valid);            // true
console.log(verification.payload.verdict);  // matches assessment.verdict