Authentication Overview

Sovrium ships authentication as a first-class platform capability powered by Better Auth. A single auth block in your app config enables sign-up, sign-in, sessions, role-based access control, and admin user management — no auth code to write.

The auth block answers one question: does this app have users? When it is present, authentication is on; when it is omitted, every /api/auth/* route returns 404 and the app is fully public.

app.yaml

auth:
  strategies:
    - type: emailAndPassword
  defaultRole: member

That four-line config gives you working email/password sign-up and sign-in, server-managed sessions, the three built-in roles, and the admin user-management endpoints.

Enabling Authentication

Authentication is enabled by the presence of the auth object. There is no auth.enabled: true flag.

State	Result
`auth` omitted	App is public. All `/api/auth/*` routes return `404`. No identity, no sessions.
`auth` present	Auth is on. Sign-up/sign-in routes mount, sessions are issued, RBAC and admin features apply.

At minimum the auth block requires a non-empty strategies array (at least one strategy, no duplicate types). Everything else is optional and layered on top.

Admin features are always on. When auth is configured, user management, role assignment, and impersonation endpoints are mounted automatically — there is no separate toggle. Registering does not grant admin: every sign-up gets defaultRole, and the first admin is created deliberately (env vars, the sovrium admin create CLI, or the one-time bootstrap token). See Roles & RBAC.

The `auth` Config Block

The auth object accepts the following top-level properties. Each links to its dedicated page.

Property	Description
`strategies`	Required. Array of authentication strategies (email/password, magic link, OAuth). At least one; no duplicate types. See Strategies.
`allowSignUp`	Boolean. Controls self-registration. `true` (default) lets anyone sign up; `false` restricts user creation to admins. See Strategies.
`roles`	Array of custom role definitions layered on top of the built-in roles. See Roles & RBAC.
`defaultRole`	Role assigned to new users on registration. Defaults to `member`. See Roles & RBAC.
`groups`	User groups for many-to-many membership and group-scoped permissions. See Groups.
`twoFactor`	TOTP-based two-factor authentication. Requires the `emailAndPassword` strategy. See Two-Factor.
`emailTemplates`	Custom subject/body for authentication emails (verification, reset, magic link, OTP, invitation, …). See Strategies.
`invitationTokenExpiry`	Lifetime of single-use admin invitation tokens. Duration string (`72h`, `7d`) or milliseconds. Defaults to `72h`.
`scopeTables`	Tables referenced by the multi-tenant `user_access` junction. Drives `$currentUser.assignments` scoping. See Sessions.
`landingPath`	Engine-resolver mount path for per-role post-login landing. See Post-Login Landing.
`noAccessPath`	Fallback path when no role's `defaultLanding` matches the session. Defaults to `/403`. See Post-Login Landing.

Infrastructure secrets (signing keys, callback URLs, OAuth credentials) live in environment variables — not in this schema. See Environment Variables.

Default Roles

Every Sovrium app with auth configured has three built-in roles available without any configuration. They cannot be redefined.

Role	Level	Access
`admin`	80	Full access — manage users, roles, settings; all table permissions.
`member`	40	Standard access to application resources (the default new-user role).
`viewer`	10	Read-only access.

The numeric level establishes a hierarchy (higher = more privileged) used by permission resolution. Custom roles slot into this hierarchy with their own level. See Roles & RBAC for definitions, hierarchy, and admin roles.

Environment Variables

One variable is required for production auth, and one is optional:

Variable	Purpose
`BASE_URL`	Required. Base URL of the app (e.g. `https://myapp.com`). Used for auth callback URLs and email links.
`AUTH_SECRET`	Optional. Signs tokens and session cookies. Derived from the app's encryption key when unset; 16 characters minimum if set.

>_ terminal

BASE_URL=https://myapp.com

Setting AUTH_SECRET pins the signing secret so that sessions survive a change of encryption key. Leaving it out is not a weaker install — the derived value is as random as the key it comes from.

Never commit AUTH_SECRET. If you set one, treat it like a database password. Setting or rotating it invalidates all active sessions. See Environment Variables for how the two secrets relate, and for the OAuth {PROVIDER}_CLIENT_ID / {PROVIDER}_CLIENT_SECRET pairs.

Complete Example

app.yaml

auth:
  # Two ways in: credentials + Google social login
  strategies:
    - type: emailAndPassword
      minPasswordLength: 12
      requireEmailVerification: true
    - type: oauth
      providers: [google, github]

  # Self-registration on, new users start as viewers
  allowSignUp: true
  defaultRole: viewer

  # One extra role beyond the built-ins
  roles:
    - name: editor
      description: Can edit content
      level: 30

  # Group membership for field-level permissions
  groups:
    - name: marketing
    - name: finance

  # TOTP 2FA (requires emailAndPassword above)
  twoFactor:
    issuer: MyApp
    backupCodes: true

Where to Go Next

Strategies — email/password, magic link, email-OTP, social/OAuth, registration control, and email templates.
Roles & RBAC — role definitions, hierarchy, and admin roles.
Groups — many-to-many membership and group-based permissions.
Sessions — session config, revocation, and active-scope sessions.
Two-Factor — TOTP setup and recovery codes.
OAuth Server — Sovrium as an OAuth/OIDC authorization server.
Post-Login Landing — per-role landing and $currentUser.assignments interpolation.
Table Permissions — how roles and groups gate per-table and per-field access.

Last updated August 11, 2026

← PreviousClient Mode Next →Strategies Overview

Edit this page Report an issue

This documentation was written with AI, so errors or outdated content are possible. Sovrium is in beta. Contributions and corrections are welcome.