Authentication

How a Full preset app signs people up and in, keeps them signed in, and decides what they may do. Implemented in examples/full-single (internal/modules/auth) on the building blocks of modules/auth. Decisions: ADR-0024, ADR-0038, ADR-0043 (two-factor authentication).

The flow#

register ──► email with a 6-digit code ──► verify-email ──► login ──► session (cookie or token)
                                                              │
                                  2FA on? ──► 202 challenge ──► login/mfa (code or recovery code)
                                                                         │
                                         /v1/auth/me, /ops/* (with a role and 2FA), your endpoints

Start the app with aps dev (or docker compose up -d --wait, go run ./cmd/migrate, go run ./cmd/api). Emails land in Mailpit at http://127.0.0.1:8025.

# 1. Create an account
curl -X POST http://127.0.0.1:8080/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"a long enough password"}'

# 2. Read the code in Mailpit, then verify the address
curl -X POST http://127.0.0.1:8080/v1/auth/verify-email \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","code":"123456"}'

# 3. Sign in and keep the token (native clients, scripts)
TOKEN=$(curl -s -X POST http://127.0.0.1:8080/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"a long enough password","transport":"bearer"}' | jq -r .token)

curl http://127.0.0.1:8080/v1/auth/me -H "Authorization: Bearer $TOKEN"

Where the code lives#

Your app owns authentication like any other module, with all four layers. The apistock library only supplies the security building blocks.

Change a rule, such as allowing only your company's email domain, in the use case (register.go); add a column with a new migration and a repository file.

Your first administrator#

/ops/* needs a platform role, and a session signed in with two-factor authentication. In development, seed data already created one: the first aps dev (or go run ./cmd/seed) creates admin@example.com with platform_admin and two-factor authentication on, and prints its random password, authenticator app key and recovery codes once, without saving them (ADR-0042). Add the key to an authenticator app and sign in as in Two-factor authentication.

To give your own account a role, in development or production, register and verify it as above, then grant the role from the app's directory:

go run ./cmd/api roles                                        # list roles and their permissions
go run ./cmd/api grant-role you@example.com platform_admin    # recorded in the audit log as "cli"

The role applies to your next request. platform_admin and ops_viewer require two-factor authentication: until the account turns it on and the session is verified with a second factor, /ops/* answers 403 mfa_required. go run ./cmd/api revoke-role <email> <role> takes a role away.

Add roles and permissions in internal/app/permissions.go; c.RequireMFA("role") makes a role require two-factor authentication. It's code, not a runtime setting, so nobody can switch it off from /ops/settings.

Two-factor authentication#

Any account can turn on two-factor authentication with an authenticator app (TOTP: Google Authenticator, 1Password, Authy and others). Roles that require it can't be used without it.

# 1. Start: send the password, get a secret and an otpauth:// URI (show it as a QR code)
curl -X POST http://127.0.0.1:8080/v1/auth/mfa/totp -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"password":"a long enough password"}'

# 2. Confirm: send a code from the app, get 10 recovery codes (shown once)
curl -X POST http://127.0.0.1:8080/v1/auth/mfa/totp/confirm -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"code":"123456"}'

# Later sign-ins take two steps: the password returns 202 and a challenge...
CHALLENGE=$(curl -s -X POST http://127.0.0.1:8080/v1/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"a long enough password"}' | jq -r .mfa.challenge_token)
# ...and a code (or "recovery_code") finishes it
TOKEN=$(curl -s -X POST http://127.0.0.1:8080/v1/auth/login/mfa -H 'Content-Type: application/json' \
  -d "{\"challenge_token\":\"$CHALLENGE\",\"code\":\"123456\",\"transport\":\"bearer\"}" | jq -r .token)

• Confirming turns it on, verifies the current session with a second factor and signs out other devices.
• Each code works once: a code already used, even on another server instance, is refused. Wait for the app's next code.
• A challenge lasts 5 minutes and allows 5 attempts; the attempts count toward the login limit.
• A recovery code works once; the user gets an email saying how many are left. POST /v1/auth/mfa/recovery-codes with a code or a passkey response replaces them all (a recovery code can't).
• Turning it off (DELETE /v1/auth/mfa/totp) needs the password and a code, recovery code or passkey response, and isn't allowed while a role requires it. Deleting the account also needs one of them.
• Password reset doesn't turn it off: the next sign-in still asks for a code.
• Lost the app and the recovery codes: an operator runs go run ./cmd/api reset-mfa <email>, which turns it off and signs the account out everywhere.

Encryption keys#

Authenticator app secrets are stored encrypted (AES-256-GCM) with AUTH_ENCRYPTION_KEYS: comma-separated id:base64key entries of 32-byte keys, the first encrypting and all decrypting.

To replace a key: put the new key first and keep the old one (k2:…,k1:…) on every instance, run go run ./cmd/api rotate-auth-keys to re-encrypt every secret, then remove the old key. Losing every key turns off everyone's second factor until operators reset it, so back keys up like database credentials.

Passkeys#

Passkeys sign people in with Face ID, Touch ID, Windows Hello, an Android phone or a security key (ADR-0044): with no password at all, or as the second factor after one. A passkey sign-in counts as two-factor authentication, so ops roles work with passkeys alone. What to configure, and for native apps where to find each value: sign-in provider setup.

Add:        POST /v1/auth/passkeys/registration → navigator.credentials.create(options) → POST /v1/auth/passkeys
Sign in:    POST /v1/auth/passkeys/login/options → navigator.credentials.get(options) → POST /v1/auth/passkeys/login
2nd factor: POST /v1/auth/login (202, methods include passkey) → POST /v1/auth/login/mfa/passkey → get() → POST /v1/auth/login/mfa {"passkey": …}
Confirm:    POST /v1/auth/passkeys/verification → get() → DELETE /v1/auth/me, DELETE /v1/auth/mfa/totp or POST /v1/auth/mfa/recovery-codes {"passkey": …}

• credential is the browser's PublicKeyCredential as JSON (credential.toJSON()); options go to PublicKeyCredential.parseCreationOptionsFromJSON or parseRequestOptionsFromJSON, or a WebAuthn helper library.
• Each ceremony works once and lasts 5 minutes. Up to 10 passkeys per account.
• The device must verify the user (biometrics or PIN). A passkey whose signature counter goes backwards is refused and recorded as auth.passkey.clone_warning.
• Adding or removing a passkey needs the password once the session's second factor is 10 minutes old, so a stolen session can't plant its own passkey. With two-factor authentication on, the session must also have verified one.
• The first passkey signs out other devices, like turning on the authenticator app.
• The last second factor can't be removed while a role requires one; reset-mfa removes passkeys too.
• In development, open the app at http://localhost:8080: browsers don't allow passkeys on 127.0.0.1.

Errors: invalid_passkey (401), passkey_not_found (404), passkey_limit_reached (409), invalid_passkey_name (422), passkeys_unavailable (503, WEBAUTHN_RP_ID not set).

Google and Apple sign-in#

People sign in with their Google or Apple account, in browsers and in native apps (ADR-0046). Each is off until its credentials are set; creating them step by step: sign-in provider setup and the app's AUTH_PROVIDERS.md.

Browser:    GET /v1/auth/{google,apple}/start?return_to=… → provider → callback → 303 to return_to (session cookie, #mfa_challenge_token=…, or #error=…)
Native app: POST /v1/auth/{provider}/nonce → SDK sign-in with the nonce → POST /v1/auth/{provider}/token {id_token, nonce}

• New people get an account with a verified email and no password (user.has_password false); they can set one with "forgot password".
• An existing account with the same email is linked when the provider has verified the email, and the owner gets an email. If that account never verified its email, its password is removed and its sessions end, so whoever registered the address without owning it loses access.
• Two-factor authentication still applies: an account with it on gets a challenge, as with a password.
• Accounts without a password confirm sensitive changes (authenticator app setup, deleting the account, passkeys, unlinking) with a sign-in less than 10 minutes old.
• The last way to sign in can't be unlinked. Deleting the account unlinks every identity and revokes Apple's tokens; Apple's "consent revoked" notification unlinks Apple too.

Errors: invalid_social_token (401), invalid_state (401), social_email_unverified (403), identity_not_found (404), last_sign_in_method (409), invalid_return_to (422), social_unavailable (503). The web flow puts the same codes in #error=, plus access_denied when the person cancels.

Browsers and native apps#

With two-factor authentication on, send transport to POST /v1/auth/login/mfa instead: that step creates the session.

• Browsers need HTTPS in production (the cookie is Secure); localhost works in development.
• Cross-site requests carrying the cookie are refused (403), so other websites can't act as your users. Set APP_CORS_ORIGINS for your own frontend's origin.
• Store native tokens in the platform's secure storage (Keychain, Keystore).

Endpoints#

What users see#

• Registration always answers "check your email", even if the address already has an account; the owner of an existing account gets an email saying someone tried to sign up.
• Wrong email or password is one answer: invalid_credentials. email_not_verified appears only after the right password.
• Forgot password always answers "check your email".
• Codes are 6 digits, expire (15 minutes to verify, 30 to reset, adjustable), allow 5 tries, and a new one replaces the old one.
• Passwords need 12 to 128 characters; weak_password says what's wrong.
• Too many attempts: 10 logins per address per 15 minutes (second factors included), 60 auth requests per minute per IP address; too_many_attempts says how long to wait.
• Two-factor authentication emails the user when it's turned on or off and when a recovery code is used.

Sessions#

• A session ends after 14 days without use or 90 days in total (runtime settings auth.session_idle_ttl, auth.session_absolute_ttl), or when signed out.
• A session is mfa_verified when it was created with a second factor, or when the user confirmed two-factor authentication in it. Roles requiring 2FA grant their permissions only to such sessions.
• Changing the password signs out other devices; resetting it or deleting the account signs out every device; turning two-factor authentication on or off signs out other devices.
• The auth_cleanup job (daily, 03:30 UTC) removes ended sessions after 7 days, old codes and sign-in challenges, and deleted accounts after auth.deleted_account_retention (30 days).

Settings#

Change them with PUT /ops/settings/{key}. The auth module also enforces hard limits of its own, so no setting can make sessions or codes unsafe. Two-factor authentication has no runtime settings.

In your own code#

Use cases get the signed-in user from the context; the middleware sets it for every request.

import authlib "apistock.dev/modules/auth"

func (s *Service) CreateProject(ctx context.Context, name string) (Project, error) {
	switch err := actor.Require(ctx, "projects.create"); {
	case errors.Is(err, actor.ErrUnauthenticated):
		return Project{}, ErrUnauthenticated
	case errors.Is(err, actor.ErrStepUpRequired):
		return Project{}, ErrMFARequired // the role requires 2FA and this session hasn't used it
	case err != nil:
		return Project{}, ErrForbidden
	}
	p, _ := authlib.PrincipalFrom(ctx) // user, session and permissions, when you need more than the actor
	// …
}

1. Declare the permission in internal/app/permissions.go and add it to a role.
2. Check it in the use case with actor.Require (or actor.Can when you only need yes or no).
3. Map your module's errors to unauthenticated (401), mfa_required (403) and forbidden (403) in module_<name>.go.

Error codes#

Audit events#

Every sign-in (successful or not), second factor (auth.mfa.challenge_succeeded, auth.mfa.challenge_failed, auth.mfa.recovery_code_used), verification, password change or reset, two-factor change (auth.mfa.totp_enabled, auth.mfa.totp_disabled, auth.mfa.recovery_codes_regenerated, auth.mfa.reset, auth.keys.rotated), sign-out, account deletion and role change is recorded with the client's IP address and user agent. See them with GET /ops/audit?action_prefix=auth.. Email addresses, secrets, codes and recovery codes are never stored in event metadata.

Troubleshooting#