Authentication
Signing in, carrying the bearer token, session lifetime, handling 401 and signing out.
Auth is Better Auth, mounted at /api/v1/auth/*. The
mobile flow is:
Sign in
POST /api/v1/auth/sign-in/email
Content-Type: application/json
{ "email": "person@superlabs.co", "password": "…" }The response body carries the user, and the response headers carry the token:
set-auth-token: kR7mQ2xVp9LwT4nZ8bC3yH6jD1sE5aFgRead set-auth-token off the headers and store it. That is your session.
Store it in the platform keychain — iOS Keychain, Android EncryptedSharedPreferences / Keystore. Never
UserDefaults, neverSharedPreferencesin the clear, never a log line. The token is the session: anyone holding it is signed in as that person.
Every later request
GET /api/v1/users/me/profile
Authorization: Bearer kR7mQ2xVp9LwT4nZ8bC3yH6jD1sE5aFgThat header is all it takes. Send it on every call, including image and file downloads (see Media).
Session lifetime
- Sessions last 7 days and refresh once a day while in use — an active user is never signed out mid-week.
- There is no refresh token. When the session expires, the person signs in again.
- A
set-auth-tokenheader on any response means the session was rotated: overwrite your stored token with the new value whenever you see one.
Handling 401
A 401 on any route means one thing: the session is gone. Clear the stored
token and route to sign-in. Do not retry, and do not attempt a refresh — there is
nothing to refresh against.
401 also arrives when a super admin deactivates the account, with a message worth showing verbatim:
{ "message": "This account has been deactivated. Contact a super admin." }Sign out
POST /api/v1/auth/sign-out
Authorization: Bearer <token>Unregister the push token first (On sign-out) — that route is guarded, so once the session is gone you can no longer call it, and the device keeps receiving notifications meant for whoever signs in next.
Other auth routes
| Method | Path | Notes |
|---|---|---|
POST | /api/v1/auth/sign-in/email | Sign in |
POST | /api/v1/auth/sign-out | Sign out |
GET | /api/v1/auth/get-session | Validate a token, get the user |
POST | /api/v1/auth/change-password | Requires the current password |
POST | /api/v1/auth/request-password-reset | Would email a reset link — not yet: no email provider is wired up, so nothing is sent. See There is no sign-up |
POST | /api/v1/auth/reset-password | Consumes the token from that link |
POST | /api/v1/auth/update-user | Name and image only — profile fields go through PATCH /users/me/profile |
GET | /api/v1/auth/list-sessions | Their other signed-in devices |
POST | /api/v1/auth/revoke-session | Sign one of them out |
There is no sign-up
Accounts are created by a super admin (POST /api/v1/admin/members), never by
self-registration. Do not build a sign-up screen — this is enforced, not a
convention:
POST /api/v1/auth/sign-up/email → 404 Not FoundThe route is switched off at the HTTP layer, so the 404 is the whole story: it does not vary with the payload, and being signed in does not change it. Point anyone asking for an account at their admin.
The onboarding flow you do need to support is a first sign-in with a password
an admin set for them, followed by POST /api/v1/auth/change-password.
A forgotten password goes the same way: a super admin sets a new one from the
Employees screen (PATCH /api/v1/admin/members/{userId}/password), which also
signs the person out of every session. Do not build a forgot-password
screen — the web app has parked its own until an email provider exists.