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_<project_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_<project_key>"

Machine token introspection

Introspects the authenticated project API key as an opaque machine token. Send the key only in x-api-key; the body accepts optional exact issuer and audience assertions and rejects raw token or API-key fields.

POST /api/v1/m2m/introspect{  "issuer": "https://api.zkauth.dev",  "audience": "zkauth:client:<client-id>"}

{  "success": true,  "data": {    "active": true,    "tokenType": "opaque",    "tokenFormat": "zkauth_project_api_key",    "subject": "client:<client-id>:key:<key-id>",    "issuer": "https://api.zkauth.dev",    "audience": "zkauth:client:<client-id>",    "client": { "id": "<client-id>", "name": "Production", "status": "active" },    "key": {      "id": "<key-id>",      "prefix": "zka_live_abcd",      "type": "live",      "scopes": ["auth.login"],      "expiresAt": null,      "lastUsedAt": "2026-06-21T00:00:00.000Z",      "rateLimitPerMinute": 100    }  }}

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 and applies replay protection.

• If user MFA is enabled, the response is a short-lived MFA challenge instead of a normal session.
• If project-required MFA is enabled and the user has no usable factor, login returns an enrollment-required response.
• The enrollment-only token is short-lived and can be used only for TOTP setup and verification.

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}

Success response

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

MFA challenge response

{  "success": false,  "code": "MFA_REQUIRED",  "data": {    "mfaRequired": true,    "token": "eyJ...",    "availableMethods": ["totp", "backup"],    "session": { "sessionId": "...", "type": "mfa_pending" }  }}

MFA enrollment-required response

{  "success": false,  "code": "MFA_ENROLLMENT_REQUIRED",  "data": {    "mfaRequired": true,    "enrollmentRequired": true,    "token": "eyJ...",    "availableMethods": [],    "session": { "sessionId": "...", "type": "mfa_enrollment" }  }}

Exchanges the pending MFA token plus a TOTP or backup code for the authenticated session.

Hosted sign-in handoff

Bearer-authenticated hosted UI endpoint that issues a short-lived, single-use handoff code for an allowlisted application callback. The response contains the redirect URL with code, not the bearer session token.

Server-side endpoint for application callbacks. Send the project API key and the handoff code to redeem the engine session token, then store it in your own secure app session cookie.

POST /api/v1/auth/hosted-handoff/redeem{  "code": "single_use_handoff_code"}

Session identity and rotation

These require the session token as a bearer token.

Return the authenticated user and current session metadata, including device, expiry, last activity, risk, MFA, and sensitive-session fields.

{  "success": true,  "data": {    "user": { "id": "usr_...", "email": "ada@example.com" },    "session": {      "id": "sess_...",      "type": "mfa_verified",      "deviceId": "dev_...",      "expiresAt": "2026-06-19T11:00:00.000Z",      "lastActivityAt": "2026-06-18T11:50:00.000Z",      "riskLevel": "low",      "trustScore": 90,      "mfaVerified": true,      "sensitiveVerifiedAt": "2026-06-18T11:45:00.000Z",      "sensitiveVerifiedFactor": "totp"    }  }}

Invalidate the current session and revoke the active bearer token.

Rotate the active session token and revoke the previous token.

• The default engine session lifetime is 24 hours, and project security policy can set a shorter or longer bounded lifetime.
• High-risk sessions may be shorter.
• Refresh preserves the original sensitive-session timestamp; it does not create a fresh MFA verification.

Return user-scoped account statistics and recent login activity for the authenticated bearer session.

Hosted helper pages route these through the project-bound hosted proxy and bound displayed network/browser metadata before rendering.

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. Device approval and denial links are separate single-use decisions; successful approval grants trust only inside the authenticated project.

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 with device/activity metadata, revoke a specific non-current session, or terminate every active session except the current one.

• Trusted-device listing, trust changes, and removals are scoped to the authenticated project.
• Removing a trusted device also invalidates matching sessions for that project.
• Terminating all other sessions requires a fresh first-factor session.
• Use /auth/logout to revoke the current session.

{  "success": true,  "data": {    "sessions": [      {        "id": "sess_...",        "deviceName": "Chrome on Windows",        "deviceType": "desktop",        "trustLevel": "trusted",        "lastActivity": "2026-06-18T11:50:00.000Z",        "expiresAt": "2026-06-19T11:00:00.000Z",        "sessionType": "mfa_verified",        "mfaVerified": true,        "sensitiveVerifiedAt": "2026-06-18T11:45:00.000Z",        "isCurrent": true      }    ],    "total": 1  }}

TOTP setup and verification require a fresh first-factor session.

• When a project-required unenrolled login uses the enrollment-only token, successful TOTP verification returns a fresh MFA-backed engine session.
• Backup-code generation, recovery-code export, and MFA disable require a fresh MFA-backed session.

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

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 error envelope:

{  "success": false,  "error": {    "code": "VALIDATION_ERROR",    "message": "One or more fields are invalid.",    "request_id": "req_...",    "docs_url": "https://zkauth.dev/docs/errors#VALIDATION_ERROR"  },  "code": "VALIDATION_ERROR",  "message": "One or more fields are invalid.",  "request_id": "req_..."}

Prefer error.code and error.request_id in new integrations. The top-level fields are compatibility fields for older clients.