Admin login, platform-wide user management, per-user session control, and admin-issued platform invites.

Admin

This guide's fixed admin/user role examples apply when app permissions are disabled. With WithAppPermissions enabled, app administrative operations can be delegated individually to custom roles through installed library keys; organization oversight and catalog provisioning remain protected-admin-only. See the app permission guide for bootstrap, enabled-mode role payloads/filters, direct service calls and current MFA enforcement.

Normal authentication runs first. Missing/expired sessions fail as usual; authorization denial returns 403 forbidden, and missing required second-factor assurance returns 403 two_factor_required. Auth.RequireAdmin always requires the protected administrator, even when other routes permit delegated operators.

One distinction that applies to every admin route: user_not_found (404) is returned only when the target user genuinely does not exist. If the database read for the target user fails instead — an outage, a canceled context — the route answers internal_error (500) and logs the cause server-side, so a temporary backend problem is never reported as a missing user. The same rule covers the middleware: session validation or transparent-refresh failures due to backend trouble produce internal_error, never 401 unauthorized — see Error handling.

For the full path/param reference see Routes. For viewing what admins (and everyone else) have done, see Audit Logs.

The curl mutation examples use jq to read the mandatory CSRF bootstrap JSON. Keep the same cookie jar for bootstrap and the following request; the bootstrap is repeated after authentication changes.

Configuration

There's no WithAdmin flag — the existing administrative routes are always mounted. Access uses the fixed account role when app permissions are off and current app authorization when on. TwoFactorConfig.DisableAdminTwoFactor opts out of the default admin requirement; global and per-user requirements still apply. Custom roles with delegated administrative permissions follow user MFA settings.

Bootstrapping the first admin

Every admin-management endpoint below requires an admin session to call — including POST /admin/users. That's a chicken-and-egg problem for the very first admin: there's no API route that creates one from nothing. Use the goauth seed-admin CLI command — see Creating the first admin below.

Creating the first admin

goauth seed-admin writes an admin user directly to the database, bypassing the API entirely — it's the supported answer to the chicken-and-egg problem above, so you don't have to hand-write an UPDATE users SET role = 'admin' WHERE email = '...' against production.

The standalone CLI does not load your application's Config, so it writes this bootstrap password as an unpeppered bcrypt row (password_pepper_version = NULL). In an application with versioned password peppering enabled, the first successful admin password check verifies that explicit legacy format and upgrades the row through the normal guarded rehash-on-login path before issuing the 2FA challenge or session. Until that first login, the bootstrap row has bcrypt protection but not the optional pepper layer.

go run github.com/nazimdjebloun/go-auth/cmd/goauth seed-admin \
  --driver postgres --dsn "$DATABASE_URL" --env prod \
  --smtp-host smtp.example.com --smtp-from auth@example.com

Because admin login requires a second factor by default, a seeded admin who can't receive email may never be able to log in — so this command sends a real verification email to the address you're seeding, before writing anything to the database, and aborts with nothing written if that send fails. This check runs regardless of whether the deployment you're seeding for has set TwoFactorConfig.DisableAdminTwoFactor — the CLI has no way to know your running server's config, so it conservatively assumes the default (2FA on). --driver, --dsn, and --env are required; --env is dev, staging, or prod and controls which mailer default applies.

That email is fixed HTML-and-text content with no app name, links, or configurable parts — it lives in cmd/goauth/cmd/seed_admin_email.go and, unlike the library's emails, does not go through TemplateProvider. A compiled CLI has no way to accept a custom provider from an operator, so there is nothing to swap.

Input	Flag	Env var	Notes
Admin email	—	`ADMIN_EMAIL`	Prompted for interactively if unset and stdin is a TTY; a hard error otherwise.
Admin password	—	`ADMIN_PASSWORD`	Validated against the default password policy if set. Otherwise prompted (hidden input) with fallback to a strong auto-generated password, printed once and never shown again.
SMTP config	`--smtp-host`, `--smtp-port`, `--smtp-from`, `--smtp-user`, `--smtp-pass`, `--smtp-tls`	`SMTP_HOST`, `SMTP_PORT`, `SMTP_FROM`, `SMTP_USER`, `SMTP_PASS`, `SMTP_TLS`	Required unless `--env dev` (see below) or `--skip-mailer-check`. The port defaults to 587; an explicit flag overrides `SMTP_PORT`. Invalid or out-of-range ports fail before seeding.
Force non-interactive	`--non-interactive`	—	Missing `ADMIN_EMAIL` fails immediately instead of prompting — for CI.
Skip the mailer send	`--skip-mailer-check`	—	Still builds a mailer if SMTP config is present; just doesn't require the send to succeed. Prints a loud warning either way.
Allow a second admin	`--force`	—	Without it, seeding refuses outright if any `role: admin` row already exists.

--env dev with no SMTP flags/env set uses a log-only mailer instead of real SMTP — the same LogMailer NewConfig defaults to automatically in EnvironmentDev. The "verification email" is written to the command's log output instead of actually sent, so local bootstrapping needs no SMTP setup at all:

go run github.com/nazimdjebloun/go-auth/cmd/goauth seed-admin \
  --driver sqlite --dsn ./dev.db --env dev

If email/password aren't supplied and stdin is a TTY, both are prompted for; otherwise both auto-generate or error per the table above. The command refuses to write anything to the database if the mailer send fails or if an admin already exists without --force — see the flag table above.

Frontend client setup

The Client examples below use the admin-specific apiRequest(method, path, body) fetch wrapper, which sends X-GoAuth-Session: admin on every request. Use it for bootstrap, login, 2FA, reads, refresh, and logout. The named-method wrapper for everything on this page lives on Client → Admin.

Same request shape as Login, but only succeeds for users whose role is "admin" — a correct password for a non-admin account fails exactly like a wrong password, and both count as a failed admin-login attempt in the audit log.

Request body

Field	Type	Required
`email`	`string`	Required
`password`	`string`	Required

Admin login requires a second factor by default

POST /auth/admin/login sends a 2FA challenge regardless of RequireEmail2FA and the account's TwoFactorEnabled setting. It therefore requires a mailer unless TwoFactorConfig.DisableAdminTwoFactor is set. The same default applies to ordinary admin password login, admin OAuth login, and privileged HTTP access. Global/per-user requirements still apply when the admin default is disabled. See Configuration and Security.

Response (200 OK) — with the default admin 2FA policy, a correct password returns a gated challenge, the same shape Login uses:

{
  "user": { "...": "role: admin" },
  "step": "two_factor",
  "codeSent": true,
  "challengeId": "c4a1...",
  "expiresAt": "2026-08-09T12:05:00Z",
  "message": "Two-factor code sent to your email"
}

No session/refresh cookie is set on the challenge response — only the 2FA binding cookie. Complete the login with POST /auth/2fa/verify ({challengeId, code}) using the code emailed to the admin; that call is what actually sets goauth_admin_session/goauth_admin_refresh. See Two-factor authentication for the full request/response shape.

If DisableAdminTwoFactor is true and neither global nor per-user 2FA is required, login instead returns the ordinary login result with user and sets the session/refresh cookies immediately. Always branch on step: "two_factor" rather than assuming a challenge.

Errors

Code	Status	Cause
`invalid_json`	400	Malformed body
`invalid_credentials`	401	Wrong password, unknown email, an OAuth-only account with no password, or correct credentials for a non-admin user — all indistinguishable on purpose
`user_banned`	403	Account is banned
`email_not_configured`	500	No mailer configured — see the callout above
`internal_error`	500	Session creation failure

Param	Type	Default	Notes
`offset`	int	`0`
`limit`	int	`20`	Max `100`
`email`	string	—	Exact match
`search`	string	—	Matches name or email
`role`	string	—	`admin` or `user` only — any other value is silently ignored, not applied as a filter
`isBanned`	bool	—	`true` or `false` — anything else is ignored, not applied as a filter
`isVerified`	bool	—	`true` or `false` — anything else is ignored, not applied as a filter
`twoFactorEnabled`	bool	—	`true` or `false` — anything else is ignored, not applied as a filter
`neverLoggedIn`	bool	—	`true` only — `last_login_at IS NULL`. Registered but never logged in since.
`lastLoginBefore`	RFC3339 timestamp	—	`last_login_at < X`, excluding users who've never logged in (that's `neverLoggedIn`'s job) — "logged in before, gone dormant since." Composable with `neverLoggedIn` for two different questions in one dashboard.
`orderBy`	string	`created_at`	Or `updated_at`; an explicitly supplied unsupported value is a 400
`orderDirection`	string	`desc`	Or `asc`; an explicitly supplied unsupported value is a 400

Admin

On this page