Auth Module Feature Guide
Functional behavior of admin auth and customer mobile auth — login, sessions, password reset, and verification.
Auth - Feature Guide
1. Feature Overview
Auth is intentionally split by actor surface:
- Admin/superadmin auth on
/api/auth/*(email/password only) - Customer mobile auth on
/api/mobile/auth/*(email/password only)
Accounts are created by an administrator through the Users and Team modules. There is no
self-service registration and no self-service account deletion. banned is the only account
control.
2. Surface Matrix
| Surface | Prefix | Register |
|---|---|---|
| Admin | /api/auth/* | No |
| Customer mobile | /api/mobile/auth/* | No |
3. Auth Features
Admin and mobile surfaces both support:
- email/password login
- refresh token rotation
- logout
- password reset (forgot + reset)
- email verification resend/confirm
Admin-only extras:
GET /api/auth/permissions- phone verification endpoints under
/api/auth/phone/verify/*
4. Account Entry Links
A person receives an emailed link in two situations, and both end on the same screen: choose a password.
| Purpose | Minted when | Lifetime |
|---|---|---|
account_invite | An administrator grants somebody sign-in access — while creating their record, or afterwards from the people screens | 7 days |
password_reset | Somebody uses forgot-password, or an administrator sends a reset link from a person's detail screen | The OTP expiry, 15 minutes by default |
Both redeem through POST /api/auth/password/reset, which accepts either purpose
in its token field. Somebody clicking a link cannot tell which of the two they
hold, and it makes no difference to what they do next. They stay separate
verification records so the two can carry different lifetimes, be audited apart,
and so an invitation nobody has redeemed can be reported on.
An invitation is redeemable by link only. A one-time code is minted alongside
it but is never rendered into the invitation email, and the OTP branch of the
reset endpoint matches password_reset alone. That is deliberate rather than an
omission: the OTP lookup selects on purpose and person with no token hash to
separate two live records, so accepting both purposes there would let a correct
code be compared against the wrong record, fail, and consume one of the five
attempts that retire it.
Redeeming either link retires the other. An invitation and an administrator's reset can be live for the same person at the same time, and once one of them has set a password the other must stop working.
A link that has expired, been redeemed, or been retired this way is refused with
AUTH_VERIFICATION_CODE_INVALID. The remedy is a fresh link, not a retry.
5. Rate-Limit Feature Notes
Throttling is enabled on high-risk routes (login, refresh, password reset, verification).
Auth Module Backend Documentation
Internal auth architecture with split admin/customer controllers for login, sessions, password reset, and verification.
Admin Route Guarding
How the admin panel decides which pages a role may open — the server guard, the exemption list, the denial and outage destinations, and the failure modes each one exists to prevent.