Youverify API Authentication: Keys, Environments, Headers

Every request to the Youverify API is authenticated with a single secret key passed in the token header — there is no OAuth handshake, no session cookie, and no bearer prefix. Possession of the key is authority, so keeping it server-side and out of client code is the single most important security step you can take.

Credential types

Youverify issues two distinct credentials per workspace environment. They serve different purposes and must never be swapped.

API Secret Key

Used for all server-to-server API calls. Pass it in the token header. Never expose this key in a browser, mobile app, or public repository — anyone who holds it can act on your workspace.

Public Merchant Key

Safe to embed in web and mobile SDKs or hosted flows. Scoped only to starting liveness and document-capture sessions. It cannot create entities, retrieve profiles, or trigger verifications.

Credential	Where used	Header / field	Can read entities?
API Secret Key	Backend / server	`token` header	✅ Yes
Public Merchant Key	Frontend / SDK	SDK initialisation	❌ No

Never include your API Secret Key in client-side JavaScript, Android/iOS app bundles, or any code that ships to end users. If you suspect a secret key has been compromised, rotate it immediately in your workspace settings.

The `token` header

Pass your secret key as the value of the token header on every server-to-server request. There is no Bearer prefix — the value is the raw key string.

POST /v2/api/entities HTTP/1.1
Host: api.sandbox.youverify.co
token: YOUR_SECRET_KEY
Content-Type: application/json

A minimal cURL example:

curl -X GET "https://api.sandbox.youverify.co/v2/api/entities/ent_685c73c8519d82bd21a42fae" \
  -H "token: $YV_SECRET_KEY" \
  -H "Content-Type: application/json"

Store your key in an environment variable (YV_SECRET_KEY) rather than hard-coding it. This keeps the key out of version control and makes rotating credentials straightforward.

Environments

Youverify operates two completely independent environments. Each has its own base URL and its own set of API credentials. A key from one environment is rejected by the other.

Environment	Base URL	Purpose	Data	Billing
Sandbox	`https://api.sandbox.youverify.co`	Integration & testing	Synthetic test data	Free — never billed
Production	`https://api.youverify.co`	Live checks	Authoritative government sources	Billed per check

Use sandbox throughout development and integration testing. Switch to production only when you are ready to process real subjects.

Do not mix environments. Using a sandbox key against the production URL (or vice versa) returns a 401 Unauthorized error. Entities and data created in sandbox never appear in production.

Where to find your keys

Your API keys live in your Youverify workspace settings:

Open your workspace

Navigate to Settings → API Keys

In the sidebar, go to Settings, then select the API Keys tab.

Select the correct environment

Use the environment selector at the top of the page to toggle between Sandbox and Production. Each environment shows its own distinct key pair.

Copy and store securely

Click Copy next to the API Secret Key and store it in a secrets manager, .env file (excluded from source control), or your deployment platform’s environment variables.

Authenticated request examples

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@example.com"
  }'

const response = await fetch(
  "https://api.sandbox.youverify.co/v2/api/entities",
  {
    method: "POST",
    headers: {
      token: process.env.YV_SECRET_KEY, // ← token header, no "Bearer" prefix
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      entityType: "individual",
      isSubjectConsent: true,
      firstName: "Jane",
      lastName: "Doe",
      email: "jane@example.com",
    }),
  }
);

import os, requests

headers = {
    "token": os.environ["YV_SECRET_KEY"],   # ← token header, no "Bearer" prefix
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.sandbox.youverify.co/v2/api/entities",
    headers=headers,
    json={
        "entityType": "individual",
        "isSubjectConsent": True,
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "jane@example.com",
    },
)

Authentication errors

When authentication fails, the API returns a standard error envelope with a machine-readable name field. The two most common authentication-related errors are:

401 Unauthorized — invalid or missing key

Your request arrived without a token header, or the key value is incorrect (wrong key, extra whitespace, or a production key against sandbox).

{
  "success": false,
  "statusCode": 401,
  "name": "UnauthorizedError",
  "message": "Invalid or missing API key. Provide your secret key in the token header."
}

Fix: Confirm the token header is present, that the key value matches what is shown in your workspace settings, and that you are using the correct environment’s key against the correct base URL.

403 Forbidden — insufficient scope

Your key is valid, but it does not have permission to perform the requested action. This typically happens when a Public Merchant Key is used on an endpoint that requires a secret key.

{
  "success": false,
  "statusCode": 403,
  "name": "ForbiddenError",
  "message": "You do not have permission to access this resource."
}

Fix: Ensure you are using the API Secret Key (not the Public Merchant Key) for server-side operations. If you have multiple roles or restricted workspace permissions, contact your workspace admin.

Security best practices

Rotate keys regularly. Generate a new key in workspace settings and update your deployment before retiring the old one.
Use environment variables. Never commit keys to Git, even in private repositories.
Scope access. Use the Public Merchant Key for any client-facing flow. Reserve the secret key exclusively for your backend.
Monitor usage. Review API activity logs in your workspace dashboard to detect unexpected usage patterns early.

Get Started

Core Concepts

Guides

Webhooks

SDKs

Youverify API Authentication: Keys, Environments, Headers

Credential types

API Secret Key

Public Merchant Key

The `token` header

Environments

Where to find your keys

Authenticated request examples

Authentication errors

Security best practices

​Credential types

API Secret Key

Public Merchant Key

​The token header

​Environments

​Where to find your keys

​Authenticated request examples

​Authentication errors

​Security best practices

Credential types

The `token` header

Environments

Where to find your keys

Authenticated request examples

Authentication errors

Security best practices