Auth · Sessions
Who a request is, how it became that, and how it stops — sessions, registration, sign-in and one-time codes.
Everything core's auth module answers to, under /api/auth. Registration and sign-in
are open; the directories and the settings are admin-only; the identity surface is guarded per
identity.
Concepts
Identity
An identity is the account. It carries a kind —
guest, member, admin, service,
developer or unknown — an id, a display name, and whichever of
username, email address and phone number it was registered with. The first identity registered
on a deployment becomes the admin.
Sessions and tokens
A successful registration or sign-in returns an identity token and a
refresh token, and sets both as HttpOnly cookies named
identity and refresh. The identity token is short-lived; the refresh
token redeems a new pair. Every session is addressable by its jti, which is what
"sign out this device" invalidates.
A request may present the identity token as the identity cookie or as
Authorization: Bearer <token>. The bearer header wins when both are present.
Service-to-service calls present the deployment's MODDABLE_SERVICE_KEY the same
way, which satisfies the admin guard.
Guards
Every route runs behind one of four postures, named on the endpoint below.
| Guard | Middleware | Rejects |
|---|---|---|
| Open | useRequestTelemetry, useRequestIdentity |
Nothing — the session is read if present. |
| Session | useRequestIdentity |
Enforced by the handler against the identity in the path. |
| Own identity | isVerifiedIdentity, isOwnIdentity('id') |
Any session that is not the identity in the path — an admin's included. |
| Admin | isVerifiedAdmin |
Anything but an admin identity or the service key. |
Authentication payload
Registration, sign-in and every challenge take the same body — a kind saying which
identifier is being presented, a method saying how it is being proven, and the
fields those two imply. It is documented per endpoint below.
Endpoints
Each endpoint below is documented in the folder of the signal that serves it — a
doc.ts beside the index.ts that registers the route — and appears here
once it is named in signals/auth/docs.ts.
The auth module serves more routes than are documented here yet. Rather than keep a second list
by hand and let it rot, the suite walks the signal tree and names every route still missing a
doc.ts: run moddable tests core unit and read the
auth doc coverage report.