Skip to navigation
Using the API

API overview

Three API families, one set of keys.

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

FamilyUse it forKeysContract
/api/kycVerification sessions, verifications, one-off checks, face match, contact verificationPublishable in clients, secret on your backendIdentity verification
/api/identityYour customer record (entities), address checks, activity events. A compatibility surface: new Risk Intelligence work belongs on /api/v1SecretIdentity verification
/api/v1Risk decisions, screening, monitoring, wallet screening, Travel Rule, cases, webhooksSecretRisk Intelligence

Base URLs

SandboxProduction
/api/kychttps://api.toden.co with a test keyhttps://api.toden.co
/api/identityhttps://api.toden.co with a test keyhttps://api.toden.co
/api/v1https://sandbox-api.toden.cohttps://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:

curl "https://api.toden.co/api/kyc/config" \
  -H "Authorization: Bearer $TODEN_PUBLISHABLE_KEY"
KeyPrefixMay call
Publishablepk_test_, pk_live_Starting a verification, uploads, configuration and minimal status. Safe in client code.
Secretsk_test_, sk_live_Everything, including results, media and all of /api/v1. Backend only.

Every endpoint page states which key it needs. Authentication covers creating, restricting and revoking keys.

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.

ContractCoversWhere
Risk Intelligence/api/v1https://api.toden.co/api/openapi.json
Identity verification/api/kyc and /api/identityLinked from Machine-readable docs

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.