Develop sign-in locally

axiom auth emulate runs a local issuer for your project directory so you can build sign-up and sign-in screens without a Cloud account, a hosted database or network access. It speaks the same JSON endpoints as an environment's issuer for the methods it emulates, captures every email instead of sending it, and offers a mock OpenID Connect provider with synthetic identities.

Use a preview branch with captured mail to test the features that are not emulated.

Start the emulator

From your project directory:

axiom auth emulate --identity jo@example.com

It prints the local issuer, the mail viewer and the mock provider, and keeps running:

The emulator listens on 127.0.0.1 only and opens no outbound connection. Storage is a disposable SQLite file holding the same authentication tables as a hosted environment. Signing keys are generated on every start. Without a settings file, the emulator enables password and email-code sign-in, open signup with email verification, and redirect URLs and allowed origins for http://127.0.0.1:5173 and http://localhost:5173.

Read sign-in codes

Verification and sign-in codes are written to the local mail store and shown at /local/mail. Nothing is sent. Point your frontend's issuer setting at the local issuer and complete sign-up with the code from the mail viewer.

Sign in with a provider

Every provider in your local settings (for example google) signs in through the mock OIDC issuer, which signs one of the --identity addresses. It never contacts the real provider and never signs a real identity.

Verify local tokens in a local server

Local tokens carry the local issuer, so every Axiom Cloud issuer and server refuses them. A local Axiom server can verify them with a jwt EdDSA provider that points at the emulator:

axiom auth emulate deployment work/deployment.json
AXIOM_AUTH_LOCAL_PUBLIC_KEY="$(cat .axiom/auth-local/public.pem)" \
  axiom server run backend/.axiom/contracts/backend.axiom \
  backend/.axiom/contracts/backend.server.json \
  --deployment work/deployment.json --listen 127.0.0.1:8080

emulate deployment rewrites the deployment's authentication to the running emulator's issuer, with the public key read from AXIOM_AUTH_LOCAL_PUBLIC_KEY. Create work/deployment.json first with axiom server deployment; see Verify tokens.

Promote the settings to Cloud

Export the local settings, compare them with an environment, then push:

axiom auth config export --from local --output work/config.json
axiom auth config diff --from local --to env:development
axiom auth config push --from local --to env:development --approvals auth/config.approvals.json

The export contains public settings and secret references only, in the form {"ref":"SECRET_NAME"}. Loopback redirect URLs, loopback origins, the mock provider, users, sessions, keys and captured mail never leave the directory.

diff names the environment and its issuer and classifies every change:

push applies changes in a fixed order (settings, providers, trusted issuers, role policy, outbound) and refuses unless every widening and credential item is listed in the approvals file for the current base revision. Exit codes: 0 applied, 6 an unapproved widening or credential item, 8 stale approvals, 2 usage error. Each change still needs the role it needs in the dashboard, for example Owner for providers.

Clean up

Stop the emulator, then delete its store, keys, captured mail and settings:

axiom auth emulate reset

Next steps

• Preview branches for MFA, passkeys, magic links and OAuth
• Auth policy releases and impact