Copy page

API Reference

API Reference Introduction

The Digital ID API Explorer documents each operation with its schemas and examples.

Operations

Operation	Authentication	Purpose
POST /v1/sessions	X-API-Key	Create a verification session and get the widget URL.
POST /v1/sessions/exchange	X-API-Key	Exchange a single-use result code for a verified-data JWT.
GET /.well-known/jwks.json	Public	Get the Ed25519 keys that verify Digital ID tokens.
GET /healthz	Public	Check service health.

The widget uses other Privy endpoints for identity input, liveness, face matching, OTP, and consent. Merchants do not call those internal endpoints.

Conventions

All requests use HTTPS with the environment base URLs. Request and response bodies are JSON (Content-Type: application/json).

The two session endpoints require the X-API-Key header from the merchant backend. The JWKS and health endpoints are public.

Rate limits, idempotency, and retries

The API returns 429 rate_limited when the client sends too many requests. API version 1.0.0 does not publish numeric rate limits. After a 429 response, reduce the request rate before you retry.

The public API contract defines no idempotency mechanism for the POST endpoints. If a create-session request times out, create a new session. The verified result can arrive through the exchange endpoint and the callback. Make result processing idempotent with session_id.

Integration sequence

1. Create a session from the merchant backend.
2. Load session_url in an iframe or WebView.
3. Receive privy:success and send exchange_code to the backend.
4. Exchange the code for a JWT.
5. Verify the JWT before you use its data.

The authoritative result is the Privy-signed JWT after the merchant backend verifies it.