Youverify API Authentication — Token Header & Keys

Every request to the Youverify API must include your secret API key in the token header. There is no OAuth handshake, no bearer token exchange, and no session initialization step — possession of the key is authority, which means it must never leave your backend. This page covers the two key types, how to locate them, example requests, and security best practices.

Authentication Method

Youverify uses a single token header for server-to-server authentication. Pass it on every request alongside Content-Type: application/json:

token: sk_live_abc123...
Content-Type: application/json

Do not prefix the key with Bearer or Basic. The header name is literally token and the value is your raw API key.

Key Types

Youverify issues two types of credentials. Use the right one for the right context:

Secret API Key

Full API access. Use for all server-to-server calls. Never expose this key in client-side code, mobile apps, or version control.

Public Merchant Key

Scoped only to SDK session initialization and hosted flows (e.g. liveness capture, document upload). Safe to embed in web or mobile clients.

Credential	Where to use	Can be client-side?
Secret API key	Server-to-server, `token` header	❌ Never
Public merchant key	Web/mobile SDKs, hosted flows	✅ Yes

Where to Find Your Keys

Retrieve your API keys from the Youverify dashboard:

Go to cowork.youverify.co and sign in to your workspace.

Open Workspace Settings

Click your workspace name or avatar in the top navigation, then select Workspace Settings.

Navigate to API Keys

In the settings sidebar, click API Keys. Your sandbox and production keys are listed separately.

Copy the correct key

Copy the key for the environment you are targeting — sandbox keys work only against https://api.sandbox.youverify.co, and production keys work only against https://api.youverify.co.

Example Request

The following curl example creates an entity using a secret API key in the token header:

curl -X POST "https://api.sandbox.youverify.co/v2/api/entities" \
  -H "token: $YV_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "individual",
    "isSubjectConsent": true,
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com"
  }'

Store your key in an environment variable (e.g. YV_SECRET_KEY) rather than hard-coding it. This makes it easy to switch environments and prevents accidental exposure.

Authentication Errors

Status	Error Name	Meaning
`401 Unauthorized`	`UnauthorizedError`	The `token` header is missing, empty, or contains an invalid key.
`403 Forbidden`	`ForbiddenError`	The token is valid but your plan or permission level does not allow this operation.

401 Example

{
  "success": false,
  "statusCode": 401,
  "name": "UnauthorizedError",
  "message": "Invalid or missing token."
}

403 Example

{
  "success": false,
  "statusCode": 403,
  "name": "ForbiddenError",
  "message": "Your current plan does not include access to this endpoint."
}

Security Best Practices

Follow these practices to keep your API keys secure:

Use environment variables

Never hard-code a secret key in source code. Load it at runtime from environment variables (YV_SECRET_KEY) or a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or GCP Secret Manager.

Use separate keys per environment

Keep sandbox and production keys entirely separate. Treat your production key as the highest-sensitivity credential in your system.

Rotate keys regularly

Generate a new secret key from the dashboard periodically, update your environment variable, and revoke the old key. Rotate immediately if you suspect a key has been exposed.

Never commit keys to version control

Add key files and .env files to .gitignore. Scan your repository history with tools like git-secrets or trufflehog before making it public.

Restrict server egress where possible

If your infrastructure supports it, restrict outbound calls to the Youverify API to a specific service or network segment so the key is used only from expected origins.

The public merchant key is safe to embed in web and mobile apps because it is scoped solely to starting a liveness or document-capture session — it cannot create entities, run verifications, or access any data.

Overview

Cowork API

Quick Check API

SDK API

Youverify API Authentication — Token Header & Keys

Authentication Method

Key Types

Secret API Key

Public Merchant Key

Where to Find Your Keys

Example Request

Authentication Errors

401 Example

403 Example

Security Best Practices

​Authentication Method

​Key Types

Secret API Key

Public Merchant Key

​Where to Find Your Keys

​Example Request

​Authentication Errors

​401 Example

​403 Example

​Security Best Practices

Authentication Method

Key Types

Where to Find Your Keys

Example Request

Authentication Errors

401 Example

403 Example

Security Best Practices