User Management

Sovrium provisions and manages users without ever requiring you to touch the database. The first administrator is created at boot; every subsequent user is created, listed and managed through the authenticated admin API. Each operation is RBAC-gated and audit-logged.

User management is available only when authentication is configured. The admin plugin turns on the moment an auth block exists — there is no separate flag.

Admin Bootstrap

The first admin cannot be created by another admin (there is none yet) or by self-registration (you do not want a stranger claiming the admin seat). Three complementary paths provision that account on a fresh database.

Env-var bootstrap (no-config)

AUTH_ADMIN_EMAIL=admin@example.com
AUTH_ADMIN_PASSWORD=SecureP@ssw0rd!
AUTH_ADMIN_NAME=System Administrator   # optional, defaults to "Administrator"

On first boot against a fresh database the server provisions the admin with a verified email and full admin-endpoint access. On later startups the path no-ops: it never creates a duplicate and never modifies an existing user, even when the email already maps to a different role. Success is logged without the password.

One-time token bootstrap

When the server boots with no AUTH_ADMIN_EMAIL set and no users in the database, it generates a 256-bit random token, prints it once in the startup banner, and accepts a single claim:

# Token appears in the banner as:
#   → First-admin token (POST /api/admin/bootstrap/claim): <64-hex-token>

curl -X POST http://localhost:3000/api/admin/bootstrap/claim \
  -H 'Content-Type: application/json' \
  -d '{ "token": "<64-hex-token>", "email": "admin@example.com", "password": "SecureP@ssw0rd!", "name": "Admin" }'

• Only the SHA-256 hash is persisted; the plaintext is printed to stdout exactly once and never logged.
• The token expires after 1 hour and can be claimed once — replays return 401.
• Once any admin exists the route returns 404: the window has closed, and even a leaked valid token cannot reopen it.

This is the path that makes "run the binary on a fresh server, open the URL, build the app live" possible. See Database Infrastructure for the zero-config database it pairs with.

Creating & Managing Users

Once an admin exists, every user-lifecycle operation runs through the admin API. Each endpoint needs an authenticated admin session — unauthenticated requests return 401, and non-admin sessions get 404: the admin surface is invisible to anyone who cannot use it, so its existence is not discoverable.

create-user requires you to invent and transmit the user's password, and sends them nothing. For onboarding real people, use an invitation instead.

Role Assignment

Moved to Invitations.

Invitation Flow

Moved to Invitations.

Related Pages

• Invitations — passwordless onboarding and the role a new user receives.
• Registration Control — whether the public may self-register.
• Roles & RBAC — role model and field-level permissions.
• Sessions — session lifetime, revocation, multi-device.
• Admin Dashboard — operator-grade read console over users and tables.
• Activity Monitoring — audit trail of user and admin actions.
• Environment Variables — full env-var reference incl. AUTH_ADMIN_*.