Guides

Deployment

ZKAuth’s engine is hosted, so “deploying” means promoting your own app from test keys to live keys and pointing it at the right configuration. There’s no engine to run yourself.

Switch to your live key

Build against the test key, then set the live key in your production environment. Keys are project-scoped and rotate independently.

bash

# Production server-only runtime configZKAuth project key = zka_live_<project_key>ZKAuth API base URL = https://api.zkauth.devApplication mode = production

Server-side only

Set keys as server environment variables. Don’t expose them to the browser or commit them to source control.

Configure passkey origins

A WebAuthn relying-party ID and origin must match the domain that serves the ceremony. The hosted service currently supports its documented canonical RP. The environment variables below apply only when you operate the customer data plane or self-hosted engine.

bash

# Customer data-plane / self-hosted engine configurationWEBAUTHN_RP_ID=your-app-domain.comWEBAUTHN_ORIGIN=https://your-app-domain.com

Hosted passkey sign-in only works for credentials registered on the hosted WebAuthn origin. It creates an engine session only after project device and MFA policy passes. A separate hosted custom domain requires verified DNS ownership, TLS provisioning, an explicit RP record, and a new credential registration. That lifecycle is not a public hosted feature yet.

Configure callbacks and browser origins

ZKAuth sends transactional emails from zkauth.dev, but the user should usually return to your app after clicking verification, device approval, device denial, or password reset links.

Set a primary redirect URL and keep every permitted callback in the allowlist.
Callback URLs are normalized, capped per project, HTTPS-required outside localhost development, and rejected when they point at private-network hosts.
Store browser origins separately from email redirect paths. Origins must be exact scheme/host/port values, with no paths, query strings, credentials, or wildcards.

txt

Primary redirect URLhttps://your-app.com/auth/callback
Allowed redirect URLshttps://your-app.com/auth/callbackhttps://staging.your-app.com/auth/callback
Allowed browser originshttps://your-app.comhttps://staging.your-app.com

Fallback pages

If no safe redirect is configured, ZKAuth shows hosted fallback pages for email verification, device decisions, and reset links.

Hosted sign-up/sign-in and hosted forgot-password/reset pages are for flows that should not expose project API keys to browser code.

Hosted sign-in can return a single-use handoff code to an allowlisted callback after engine authentication. Redeem it from trusted server code with the project API key, then create your app session cookie.

Hosted account-helper controls use the engine bearer token only in component memory, and hosted reset completion still does not create an application session.

Project email templates can override the subject and body copy for current transactional security emails. Overrides are text-only: ZKAuth still renders the fixed HTML shell, action buttons, fallback links, escaping, and plain-text alternatives.

Performance expectations

The historical Proof V1 harness reported a 446.878 ms mean across 1000 local proof-plus-controller runs. It did not exercise the current ceremony-bound Proof V2 protocol and is not a current latency claim.

The August 9 Proof V2 benchmark completed three 30-login trials against the real local engine and disposable PostgreSQL 17. The median trial measured a 229.8 ms warm p50, 240.8 ms warm p95, and 590.1 ms cold login. A separate 30-login SDK mock-server diagnostic measured 154.2 ms p50 and 160.4 ms p95.

Completion reruns on the current engine and SDK commits showed local host/load variance: 691.3-707.0 ms warm p50, 745.5-835.6 ms warm p95, and 1.87-1.88 s for a fresh-process cold login. Preload the public proof artifacts before an interactive login, and do not promise a universal sub-800 ms cold start.

Both measurements used loopback HTTP and warmed local artifacts. They are not hosted SLOs: hosted calls add network, serverless, proxy, and remote-database latency. Measure the deployed path before choosing user-facing timeouts.

Go-live checklist

Swap zka_test_ -> zka_live_ in production env.
Confirm keys are server-side only and not in client bundles.
For a customer data plane, set WEBAUTHN_RP_ID / WEBAUTHN_ORIGIN per environment. Hosted projects use the documented canonical RP.
Set and allowlist your auth callback URLs.
Set exact browser origins for every production and preview app.
Store session tokens in http-only, secure cookies.
Validate the live key with GET /api/v1/client/me.
Watch usage and API logs in the dashboard after launch.

Verify before you ship

A quick key check catches most misconfigurations. See API reference for the request.