# API Reference Introduction

The [Digital ID API Explorer](/digital-id/api) 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](/digital-id/concepts/environments). 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.