Authentication
Device bearer tokens — no accounts required.
There are no accounts in the traditional sense. A device is the subject, and it proves itself with a bearer token, not with its identifier.
POST /api/v1/auth/device (no body, no auth)
→ { "device_id": "…", "token": "…" }The token is issued once per install and returned exactly once — it
cannot be re-fetched. Only its SHA-256 is stored server-side
(users.token_hash), so a database leak doesn't hand over credentials.
Every per-user endpoint takes it as a bearer header:
Authorization: Bearer <token>The device id never appears in a path or query
It used to. That meant anyone holding one could read that person's profile, cancel their Plus, or delete their account — a device identifier is not a secret (iOS hands the same one to every app from a vendor), and anything in a URL lands in proxy and access logs. The token is the identity now, so a caller has no way to name anybody but itself. The server, not the client, generates the id, so there's nothing to guess or claim either.
On the client, the token lives in the Keychain (kSecClassGenericPassword,
kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly) — it survives deleting
the app, which is what lets a reinstall keep its profile. A 401 means the
row behind the token is gone; the iOS client's DeviceAuth actor registers
afresh and retries once, single-flighted so concurrent callers don't
double-register.
Which endpoints need a token
| Endpoint | Auth |
|---|---|
/health*, /products/search, /query, /trending, /alternatives | none |
/products/needs-verification | optional — a token lets it skip products you've already voted on |
/products/verify, /ocr/submit, all of /me/* | required |
Sign in with Apple
Sign in with Apple is additive, never required — nothing in the app needs an account. It's the only identity provider (no passwords, no email delivery).
POST /api/v1/me/link verifies the identity token end to end before
writing anything: Apple's signature, over Apple's published key, issued by
Apple, with this app's bundle id (APPLE_BUNDLE_ID) as audience, unexpired.
Apple's keys are cached for six hours and re-fetched on an unknown key id.
If that Apple identity already owns a row on another device, the account moves — Plus state and preferences come across, the old row is deleted, and that other phone reverts to anonymous. One active device per account; there's no cross-device sync, so anything else would silently duplicate an entitlement.
POST /api/v1/me/unlink detaches the identity and keeps the row (what
signing out should do — nothing is destroyed). DELETE /api/v1/me/account
deletes the row for real, as the App Store requires for any app that
creates accounts. Verifications the device submitted are left alone — they
carry no identity beyond a device id, and removing them would silently
unverify products other people rely on.
Needs a paid Apple Developer Program team
A personal team can't create a provisioning profile that declares the
Sign in with Apple entitlement, so it fails outright rather than
degrading. The iOS build ships with the capability off
(Capabilities.signInWithApple = false, no CODE_SIGN_ENTITLEMENTS on
the target) and the account screen falls back to a display name the
person chooses via PUT /me/profile. The backend is live either way —
flipping the capability on is a client-only change.
Dashboard staff accounts
/api/v1/admin/* is a second, unrelated identity system — see
auth.rs's AdminUser extractor versus Device above. Where a device is
anonymous and proven by a bearer token alone, a dashboard account
(dashboard_users) is a named person with an email and a real password,
Argon2-hashed (not the SHA-256 used for device tokens — a password is
worth phishing, a 244-bit random device token is not).
POST /api/v1/admin/auth/register {name, email, password, date_of_birth?, occupation?}
POST /api/v1/admin/auth/login {email, password}
GET /api/v1/admin/auth/me
POST /api/v1/admin/auth/logoutOnce past that, the mechanics are the same as device auth on purpose:
register/login mint a token, only its hash is stored
(dashboard_users.token_hash), and every /admin/* endpoint after that
takes it as Authorization: Bearer <token>. Logging in mints a new
token and overwrites the stored one — a second login (a different browser)
signs the first one out. One active session per account, the simple
choice for a handful of staff.
A session also expires on its own 30 days after token_issued_at, checked
on every request (auth.rs's ADMIN_SESSION_TTL_DAYS) — a token from a
lost laptop or an abandoned browser tab stops working eventually instead
of staying valid forever, without needing a stateful blocklist. Deliberately
not JWT: a JWT's whole appeal is skipping the per-request lookup, which
is irrelevant for a handful of staff rows, and getting that speed back
would mean giving up instant revocation-by-deleting-the-row — the wrong
trade for an admin surface. The lookup itself is one indexed row read
(idx_dashboard_users_token_hash), not a scan.
The first account is the admin
Registration checks SELECT COUNT(*) FROM dashboard_users first — zero
rows means this is the first account and it gets role = 'admin'
automatically. That is what makes "I'll be the admin" true without a manual database edit.
Self-service registration & new-user role
Self-service registration (/register) is open to anyone without requiring an existing token.
New accounts registered via self-service receive the new-user role:
- Permissions: View-only access to Crash Reports, their own profile, and password management.
- Elevation: Users can submit an access request via
POST /api/v1/admin/auth/request-access. - Admin Invite: An administrator inviting a teammate via the Team tab (
POST /api/v1/admin/auth/registerwith an admin session) creates the user with thememberrole immediately. - Instant Webhooks: Webhook notifications are dispatched when new users register, when access is requested, and when roles or permissions are updated.
Password recovery
PATCH /admin/auth/password (self, requires the current password) and
PATCH /admin/team/{id}/password (admin-only, no current-password check —
for a locked-out teammate) cover every case except one: the sole admin
forgetting their own password, since by definition there's no other admin
left to call the second endpoint on them. That's a manual recovery, not an
API — see Deployment → Recovering a locked-out sole
admin.
Full endpoint list — crash reports, team management — is in API Reference → Admin.

