Let your app's admins manage users (auth.users)

Many apps have their own admins: the manager of a CRM adds a new sales rep, a school admin adds teachers. auth.users lets them do that from inside your app, with their own session. You choose which app roles may do it; nobody else can, and no server key ever goes into the browser.

#Turn it on

1. 1

   Have the roles

   Your app's roles are in Authentication › Roles (for example ADMIN, SALES). Give at least one person the admin role (console Users page, or auth.admin).

2. 2

   Choose who manages users

   In Authentication › Users, under Who can manage users in your app, tick the roles (for example ADMIN) and save. It is off until you do (no roles). The setting is userAdminRoles in the project settings; only the project team can change it.

3. 3

   Build the screen

   Call auth.users from your app. Sovariq can do all of this for you: ask for "an admin page where admins add staff".

#Use it

// Show the screen only to people the server says can use it.
const { can_manage_users, assignable_roles } = await sovaria.auth.users.access()

const { users, nextCursor } = await sovaria.auth.users.list({ search: 'ada', status: 'active', limit: 50 })

// Every user, 100 per request following the cursor (stops after max, default 10,000)
for await (const u of sovaria.auth.users.all({ role: 'SALES' })) console.log(u.email)

// Invite by email (a sign-in link), or make a temporary password shown once:
const { user, temporary_password } = await sovaria.auth.users.create({
  email: 'rep@acme.com', name: 'New Rep', roles: ['SALES'], mode: 'temporary_password',
})

await sovaria.auth.users.setRoles(user.id, ['SALES', 'MANAGER'])
await sovaria.auth.users.disable(user.id)     // signed out everywhere, can't sign in
await sovaria.auth.users.enable(user.id)
await sovaria.auth.users.delete(user.id)

#Temporary passwords

With mode: 'temporary_password' the server makes a strong password that meets your password rules and returns it once, only to the admin who made the account. Show it on screen so they can hand it over; never store it, log it or send it to analytics. The account is marked must_change_password (user.app_metadata.must_change_password, and must_change_password on /auth/me) until the user sets their own password with updateUser({ password, currentPassword }) or a password reset. If email verification is on, the user also confirms their email the first time.

The server enforces it. Until the password is changed, that user's session gets 403 PASSWORD_CHANGE_REQUIRED on every data call: tables (REST, GraphQL), storage, functions, realtime, agents, and managing users. Only these still work: reading and updating their own account (GET/PATCH /auth/me, auth.updateUser), the confirmation code for the change (auth.reauthenticate), signing out, refreshing and the password reset. A user an admin never gave a temporary password is not affected.

// At sign-in: send the user to a "choose a new password" screen first.
const me = await sovaria.auth.me()
if (me.must_change_password) {
  const { error } = await sovaria.auth.updateUser({ password: newPassword, currentPassword: temporaryPassword })
  if (!error) await sovaria.auth.refreshSession()   // the refreshed session no longer carries the flag
}

Refresh right after the change: the access token used for the change still carries the flag until it is refreshed or expires. The starter app does all of this for you: its PasswordChangeGate shows the screen and changePassword refreshes the session. If your own server verifies Sovaria tokens with the project's signing keys, check app_metadata.must_change_password in the claims as well.

#What the server enforces

Nothing here trusts your app's code. A user who edits the page in their browser, or sends requests by hand, gets the same answers as your UI:

• Every change is recorded on both accounts' security activity (auth.app_admin.* for the admin, admin.app_user.* for the user) and in your project's audit log.
• The user gets a security email when their roles change, their account is disabled or turned back on, or it is deleted (unless you turned security notifications off).
• Row security is unchanged: managing users gives no extra access to your tables. Rules like auth.has_role('ADMIN') keep deciding which rows anyone sees.
• Your team keeps the console and auth.admin (server code) for everything, including people the in-app admins can't touch.