API Reference

Valyd REST API

Versioned, JSON-over-HTTPS, predictable. Same endpoints in test and live mode — only the key prefix changes. Base URL: https://api.valyd.id

Introduction

The Valyd API is organized around REST. We use standard HTTP verbs, return JSON-encoded responses, and rely on conventional HTTP status codes. Every response includes a request_id header for support correlation.

Authentication

Authenticate with your secret key in the Authorization header. Test keys (sk_test_…) only touch sandbox data; live keys (sk_live_…) are scoped per-project.

curl https://api.valyd.id/v1/identity \
  -H "Authorization: Bearer sk_test_4f8a3b2c1d9e7f6a..."

Never embed live keys in client code

Treat sk_live_… like a database password. Use pk_live_… publishable keys for any browser-side flow.

Rate limits

Mode	Limit	Burst
Test	100 req / sec	200
Live (default)	10,000 req / min	2,000 / sec
Live (enterprise)	Negotiated	Custom

Every response includes X-RateLimit-Remaining and X-RateLimit-Reset. Exceeding the limit returns 429 Too Many Requests with a Retry-After header. SLA: 99.95% monthly uptime, EU + US regions, sub-100ms p50 latency.

Idempotency

Pass an Idempotency-Key header on any state-changing request to safely retry. Keys are valid for 24 hours and must be unique per request body. Replays return the original response.

curl https://api.valyd.id/v1/identity/verify \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: a1b2c3d4-..." \
  -d '{ "person": "person_8YQz..." }'

Versioning

The API is versioned by URL path (/v1/). Breaking changes ship under a new major version; additive changes (new fields, new endpoints) deploy continuously. Pin a date with theValyd-Version header to lock behavior.

Identity

Create an identity

POST/v1/identity

Creates a new identity record from a verified person — typically right after OAuth callback.

Param	Type	Notes
`email`	string	Required.
`full_name`	string	Optional.
`metadata`	object	≤20 keys, string values ≤500 chars.

Verify an identity

POST/v1/identity/verify

curl https://api.valyd.id/v1/identity/verify \
  -H "Authorization: Bearer sk_test_..." \
  -d '{
    "person": "person_8YQz...",
    "checks": ["face_match", "license:nurse"],
    "context": "telehealth_session"
  }'

Retrieve an identity

GET/v1/identity/:id

List credentials

GET/v1/identity/:id/credentials

Agents

Create an agent

POST/v1/agents

Authorize an agent

POST/v1/agents/:id/authorize

Webhooks

Create a webhook endpoint

POST/v1/webhooks

Errors

See the full errors reference for codes, retry guidance, and example payloads.

Request a test key →