API Reference

API reference for age verification widget integration.

Base URL

Production

https://api.vouchid.co

Test

https://api.test.vouchid.co

Authentication

Most API endpoints use API key authentication via the x-application-key header:

x-application-key: YOUR_APPLICATION_API_KEY

The token validation endpoint uses Bearer token authentication:

Authorization: Bearer YOUR_APPLICATION_API_KEY

If you're looking for the full OpenAPI surface, the backend also serves Swagger UI at /docs on the API host (for example, https://api.vouchid.co/docs).

Endpoints

🔐POST /api/verifications/validate-platform-token

Validate a platform session token received from the vouchID widget. This endpoint verifies token authenticity, expiration, and returns verification details. Use this to securely validate age verification results on your backend.

Authentication

This endpoint requires Bearer token authentication with your Application API Key:

Authorization: Bearer YOUR_APPLICATION_API_KEY

Request Body

{
  "platformSessionToken": "token-received-from-widget"
}

Example Request

curl -X POST https://api.vouchid.co/api/verifications/validate-platform-token \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_APPLICATION_API_KEY" \
  -d '{
    "platformSessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Response

{
  "valid": true,
  "ageVerified": true,
  "scopedVid": "scoped_a1b2c3d4e5f6g7h8i9j0",
  "applicationId": "app_your_application",
  "issuedAt": "2024-01-15T10:30:00.000Z",
  "expiresAt": "2024-01-15T11:30:00.000Z",
  "sessionExists": true,
  "storageType": "redis_only",
  "verificationDetails": {
    "verifiedAt": "2024-01-15T10:30:00.000Z",
    "verificationMethod": "financial_provider"
  }
}

Request Parameters

platformSessionToken - Token received from widget postMessage event

Response Fields

valid - Whether the token is valid and not expired
ageVerified - Whether user completed 18+ verification
scopedVid - Unique identifier for this user in your application
verificationDetails - Details about the verification method used

Error Responses

All endpoints return errors in the following format:

{
  "error": "string describing what went wrong",
  "code": "MACHINE_READABLE_CODE",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/verifications/validate-platform-token",
  "requestId": "req_123abc"
}

HTTP Status Codes

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error