> Toden documentation. For the full index fetch /llms.txt. Every page is available as Markdown by appending .md to its URL. Identity verification uses /api/kyc, Risk Intelligence uses /api/v1; they are separate contracts with different error shapes. Never invent an endpoint, field or enum value: read the API reference page for the operation first.

# API overview

> Base URLs, authentication, environments and the contracts behind the Toden API reference.

The reference is generated from the same contracts the server is checked against, so every endpoint, field and status code here exists in the released API. Each endpoint page has an explorer: pick an environment, paste a **test** key, and send a real request.

## The three families

| Family                                        | Use it for                                                                                                                                 | Keys                                           | Contract              |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | --------------------- |
| [`/api/kyc`](/api-reference/verification)     | Verification sessions, verifications, one-off checks, face match, contact verification                                                     | Publishable in clients, secret on your backend | Identity verification |
| `/api/identity`                               | Your customer record (entities), address checks, activity events. A compatibility surface: new Risk Intelligence work belongs on `/api/v1` | Secret                                         | Identity verification |
| [`/api/v1`](/api-reference/risk-intelligence) | Risk decisions, screening, monitoring, wallet screening, Travel Rule, cases, webhooks                                                      | Secret                                         | Risk Intelligence     |

## Base URLs

|                 | Sandbox                                | Production             |
| --------------- | -------------------------------------- | ---------------------- |
| `/api/kyc`      | `https://api.toden.co` with a test key | `https://api.toden.co` |
| `/api/identity` | `https://api.toden.co` with a test key | `https://api.toden.co` |
| `/api/v1`       | `https://sandbox-api.toden.co`         | `https://api.toden.co` |

The key prefix always names the environment: `_test_` for Sandbox, `_live_` for Production. A key used against a host that does not serve its environment is refused with `403 environment_mismatch`.

## Authentication

Send your key as a Bearer token on every request:

```bash
curl "https://api.toden.co/api/kyc/config" \
  -H "Authorization: Bearer $TODEN_PUBLISHABLE_KEY"
```

| Key         | Prefix                 | May call                                                                                 |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------- |
| Publishable | `pk_test_`, `pk_live_` | Starting a verification, uploads, configuration and minimal status. Safe in client code. |
| Secret      | `sk_test_`, `sk_live_` | Everything, including results, media and all of `/api/v1`. Backend only.                 |

Every endpoint page states which key it needs. [Authentication](/get-started/authentication) covers creating, restricting and revoking keys.

> **Warning**
>
> Use test keys in the explorer. A request sent from the explorer is a real request against the environment you select.

## Download the contracts

Both contracts are OpenAPI 3.1 documents.

| Contract              | Covers                         | Where                                                                 |
| --------------------- | ------------------------------ | --------------------------------------------------------------------- |
| Risk Intelligence     | `/api/v1`                      | `https://api.toden.co/api/openapi.json`                               |
| Identity verification | `/api/kyc` and `/api/identity` | Linked from [Machine-readable docs](/get-started/ai/machine-readable) |

## Conventions

* Bodies are JSON, except media uploads, which are `multipart/form-data`.
* Timestamps are ISO 8601 in UTC, for example `2026-04-27T12:00:00.000Z`.
* IDs are opaque strings. Store them; do not parse them.
* New optional fields, endpoints and webhook event types can be added at any time. Ignore fields and events you do not recognise.

Retries, idempotency, pagination and versioning are covered in [Requests, retries and idempotency](/api-reference/conventions).