ZKAuth
Get started

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 environment (your app)ZKAUTH_API_KEY=zka_live_your_production_keyZKAUTH_BASE_URL=https://api.zkauth.devNODE_ENV=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

Configure callback URLs

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.

txt
Primary redirect URLhttps://your-app.com/auth/callback
Allowed redirect URLshttps://your-app.com/auth/callbackhttps://staging.your-app.com/auth/callback
Fallback pages. If no safe redirect is configured, ZKAuth shows hosted fallback pages for email verification, device decisions, and password reset. They are a safety net, not the ideal production path.

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.
  • 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.
PreviousExamplesNext Changelog