API reference (canonical SDK doc)

# Age Verify API Reference

Base URL: `https://ageverify.dev`

Auth: `Authorization: Bearer <api_key>` for integrator endpoints.

## SDK client

```ts
import { createAgeVerifyClient } from 'age-verify';

const client = createAgeVerifyClient(options);
// options: AgeVerifyClientOptions
// Returns: AgeVerifyClient
```

Options (`AgeVerifyClientOptions`):
- `apiBaseUrl` — base URL of the Age Verify platform (e.g. `https://ageverify.dev`)
- `apiKey?` — secret API key; backend-only; throws if passed in browser runtime
- `allowInsecureBrowserApiKey?` — test-only escape hatch, default `false`

### `AgeVerifyClient` methods

| Method | Description |
|--------|-------------|
| `evaluatePolicy(context)` | Evaluate policy for a request context |
| `createVerificationSession(input, options?)` | Create a new verification session |
| `submitBiometricResult(sessionId, input, options?)` | Submit biometric check result |
| `submitCheckboxCompanionResult(sessionId, input)` | Submit checkbox companion result |
| `getBillingStatus(merchantId, options?)` | Get billing status for an operator |
| `getModelAccess(sessionId, options?)` | Request short-lived model access token |
| `listIntegratorApiKeys(merchantId, options?)` | List active API keys for a merchant |
| `createIntegratorApiKey(merchantId, options?)` | Create a new API key for a merchant |
| `rotateIntegratorApiKey(merchantId, keyId, options?)` | Rotate an existing API key |
| `revokeIntegratorApiKey(merchantId, keyId, options?)` | Revoke an API key |
| `initiateFallback(sessionId)` | Initiate fallback handoff to external vendor |

Compatibility note:
- `getBillingStatus(merchantId)` currently maps to `/api/v1/billing/status/{operatorId}`. Pass operator UUID.

### Standalone functions

```ts
import {
  createAgeVerifyClient,
  runDefaultBiometricCheck,
  runBiometricDemoCheck,
  AgeVerifyError,
  AgeVerifyClient,
} from 'age-verify';
```

- `createAgeVerifyClient(options)` — create an authenticated SDK client instance
- `runDefaultBiometricCheck(options)` — run the browser biometric age-estimation pipeline; returns `BiometricCheckResult`
- `runBiometricDemoCheck(options)` — run a demo (non-billable) biometric check
- `AgeVerifyError` — typed error class thrown by SDK methods
- `AgeVerifyClient` — TypeScript class/interface for the client

### Core TypeScript types

| Type | Description |
|------|-------------|
| `AgeVerifyClientOptions` | Options for `createAgeVerifyClient(options)` |
| `RequestOptions` | Per-request overrides (timeout, signal, etc.) |
| `VerificationSessionCreateInput` | Input for `createVerificationSession` |
| `VerificationSessionCreateResponse` | Response from `createVerificationSession` |
| `VerificationSessionBiometricInput` | Input for `submitBiometricResult` |
| `VerificationSessionBiometricResponse` | Response from `submitBiometricResult`; contains canonical `outcome` field |
| `DefaultBiometricOptions` | Options for `runDefaultBiometricCheck(options)` |
| `BiometricCheckResult` | Return type of `runDefaultBiometricCheck`; contains `passed`, `reason`, `subjectId` |
| `BillingStatusResponse` | Response from `getBillingStatus` |
| `ModelAccessResponse` | Response from `getModelAccess`; contains `modelBasePath`, `modelAccessToken` |

## Endpoint reference

### `POST /api/v1/policy/evaluate`

Request:
```json
{
  "operatorId": "11111111-1111-1111-1111-111111111111",
  "action": "view_page",
  "route": "/checkout",
  "category": "alcohol"
}
```

Response includes policy decision fields such as:
- `verificationRequired`
- `allowedMethods`
- `preferredMethod`
- `thresholdAge`
- `billableClassificationIfFresh`
- optional fallback context metadata

### `POST /api/v1/verification-sessions`

Request:
```json
{
  "operatorId": "11111111-1111-1111-1111-111111111111",
  "idempotencyKey": "idem_1234567890",
  "userId": "user_abc"
}
```

Response includes:
- `sessionId`
- `status`
- `identityMode`
- `policyConfig`
- `policyDecision`
- `protocolFee`
- `meterEventName`
- protocol/meter metadata

### `POST /api/v1/verification-sessions/{sessionId}/model-access`

Response:
```json
{
  "sessionId": "vs_xxx",
  "modelBasePath": "/api/v1/model-assets",
  "modelAccessToken": "...",
  "expiresAt": "2026-03-10T12:34:56.000Z"
}
```

### `POST /api/v1/verification-sessions/{sessionId}/biometric-result`

Request:
```json
{
  "outcome": "passed",
  "subjectId": "subject_abc",
  "reason": "optional_reason",
  "method": "biometric"
}
```

Legacy compatibility: `passed: boolean` is still accepted but deprecated in favor of `outcome`.

Response includes canonical outcome field:
```json
{
  "outcome": "passed",
  "status": "biometric_passed"
}
```

Canonical `outcome` values: `"passed"` | `"failed"` | `"inconclusive"`. Use `outcome` for all new integrations. The legacy `passed` boolean field is retained for backward compatibility but is deprecated.

Typical responses:
- success (with canonical `outcome` field and final `status`)
- `402` with `error: billing_blocked`
- idempotent replay for already-completed session state

### `POST /api/v1/verification-sessions/{sessionId}/checkbox-result`

Request:
```json
{
  "passed": true
}
```

### `GET /api/v1/billing/status/{operatorId}`

Response:
```json
{
  "operatorId": "11111111-1111-1111-1111-111111111111",
  "merchantId": "merchant_123",
  "billingStatus": "active",
  "hasDefaultPaymentMethod": true,
  "onboardingComplete": true
}
```

`BillingStatusResponse` in the SDK currently types `merchantId`, `billingStatus`, `hasDefaultPaymentMethod`, `onboardingComplete`, and optional `note`.

### `POST /api/v1/fallback/initiate`

Request:
```json
{
  "verificationSessionId": "vs_xxx"
}
```

Returns fallback handoff context if policy/config permits fallback.

## Error format

```json
{ "error": "..." }
```

## Exported SDK constants

Primary exports (`import { ... } from 'age-verify'`):
- `SDK_VERSION`
- `PAYER_MODE`
- `INTEGRATOR_FEES_SUPPORTED`

## Legacy exports (`age-verify/legacy`)

> **Deprecated.** Import from `age-verify/legacy` for backward compatibility only. Do not use in new integrations.

```ts
import { PROTOCOL_FEE } from 'age-verify/legacy';
```

- `PROTOCOL_FEE` — moved to `age-verify/legacy`. Use platform billing APIs for fee information.