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

If you use WebAuthn passkeys, the relying-party ID and origin must match the domain that serves the ceremony, so they differ between preview and production.

bash

# Per environment: must match the domain serving the ceremonyWEBAUTHN_RP_ID=your-app-domain.comWEBAUTHN_ORIGIN=https://your-app-domain.com

The hosted passkey verification helper only works for credentials registered on the hosted WebAuthn origin. For app-domain passkeys, serve the ceremony from your application and proxy the engine request server-side.

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

A local 1000-run benchmark measured a 446.878 ms mean proof-plus-controller login time with zero failures.

Hosted calls can be slower because they include serverless cold starts, proxy work, and remote database latency. Budget for that in 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.
Set WEBAUTHN_RP_ID / WEBAUTHN_ORIGIN per environment.
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.