Reference

API reference

The engine is REST over JSON and enforces HTTPS. Most endpoints are plain requests, but register and login carry zero-knowledge material that the client computes from the password, which is why the SDK generates it for you.

Base URL

https://api.zkauth.dev

Authentication

Send your project key in x-api-key on every request. Routes that act on a signed-in user also need the session token as a bearer token. Bearer-only requests and invalid keys are rejected.

x-api-key: zka_live_your_api_key        # every requestAuthorization: Bearer <session-token>   # user routes only

Validate a key

Returns the client that owns a key: a fully self-contained request, so it’s the best first call to confirm your setup in any language.

curl https://api.zkauth.dev/api/v1/client/me \  -H "x-api-key: zka_test_your_api_key"

Register

The body carries a client-derived salt and commitment, never the password. The SDK computes these; if you implement them yourself you must reproduce the Argon2id + Poseidon derivation.

POST /api/v1/auth/register{  "email": "ada@example.com",  "salt": "...",          // derived from the password on the client  "commitment": "...",    // Poseidon commitment, computed on the client  "deviceInfo": { "deviceName": "Chrome on Mac", "deviceType": "desktop" }}

Log in

Returns the public salt for a user (the SDK fetches this for you).

Verifies a Groth16 proof, applies replay protection, and starts a session.

POST /api/v1/auth/login{  "email": "ada@example.com",  "proof": { "pi_a": [...], "pi_b": [...], "pi_c": [...], "protocol": "groth16", "curve": "bn128" },  "publicSignals": ["..."],  "deviceInfo": { "deviceName": "Chrome on Mac", "deviceType": "desktop" },  "proofNonce": "...",  "proofTimestamp": 1730000000000}

Response

{  "success": true,  "data": {    "token": "eyJ...",    "user": { "id": "usr_...", "email": "ada@example.com", "emailVerified": true },    "session": { "sessionId": "...", "expiresAt": "..." }  }}

Session

These require the session token as a bearer token.

Return the authenticated user.

Invalidate the current session.

Confirm an email with the token from registration.

Password reset

Request a reset, verify the token, then set a new commitment. Resets may require approval depending on your project policy. Password reset emails redirect to the project callback URL with zkauth_action=password_reset and token.

Devices

List, trust, verify, and remove a user’s devices.

OPAQUE

Migration endpoints support user-mediated movement from legacy password proof credentials to persisted OPAQUE records.

WebAuthn

Route these through your backend proxy so the key stays server-side. See Authentication.

Sessions & account security

User-scoped controls under /api/v1/security, all bearer-authenticated.

List active sessions and revoke a specific one.

Set up TOTP and issue one-time recovery codes.

Start, confirm, inspect, or cancel account recovery. Confirming is gated by the configured delay.

Refresh a session token.

Webhooks

Project-scoped webhook management endpoints.

Use signed test deliveries before enabling production event delivery.

Transparency & evidence

Read-only endpoints that expose how the engine is actually configured, so you can verify our security claims instead of taking them on faith.

The active cryptographic parameters (curve, hash, Argon2id settings).

Standards mappings, published without claiming certification.

Post-quantum readiness posture.

Assurance and evidence records for operator and auditor review.

Key formats & limits

Rate limits apply per client. Failed requests return a non-2xx status with a JSON body: { success: false, message, code }.