docs
Backend

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

EndpointAuth
/health*, /products/search, /query, /trending, /alternativesnone
/products/needs-verificationoptional — 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/logout

Once 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/register with an admin session) creates the user with the member role 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.

On this page