docs
BackendAPI Reference

Admin & Crash Reports

The dashboard's API surface — a separate auth system from the rest of this reference.

Everything on this page is for web/apps/dashboard, not the iOS app. Auth is bearer tokens for named dashboard_users, not devices — see Authentication → Dashboard staff accounts for register/login/me/logout, which aren't repeated here.

PATCH /api/v1/admin/auth/password  { current_password, new_password } — self, requires the current password

Self-service password change. Requires the current password on purpose — the bearer token alone proves "a live session," not "this is really the account owner." 20/hr rate limit, same as login attempts, since a wrong current_password guess is exactly as guessable. See also Team for resetting a different account's password, and Authentication → Password recovery for the sole-admin-locked-out case this doesn't cover.

Submitting a crash report

POST /api/v1/crash-reports — unauthenticated, 200/hr per address

The one endpoint on this page a device calls, not a staff member — a crash can happen before a device has finished registering, so filing one can never depend on a token. This is what iOS's CrashReporter posts to (see iOS: crash reporting), and it's also reachable directly for anything with no automated path.

{
  "platform": "ios",
  "title": "Signal 6",
  "description": "optional",
  "stack_trace": "optional, up to 20,000 characters",
  "app_version": "optional",
  "os_version": "optional",
  "device_model": "optional",
  "severity": "critical",
  "device_id": "optional — a loose correlation id, not an auth credential"
}

platform is one of ios / backend / web. severity defaults to medium if omitted; one of low / medium / high / critical.

Managing reports

GET   /api/v1/admin/crash-reports                — list, any signed-in staff account
POST  /api/v1/admin/crash-reports                 — file one by hand, any signed-in staff account
GET   /api/v1/admin/crash-reports/{id}
PATCH /api/v1/admin/crash-reports/{id}             { status?, severity? }
POST  /api/v1/admin/crash-reports/{id}/github-issue — admin role only

GET (list) takes status, platform, severity, q (matched against title and description, case-insensitive), limit (default 50, max 200), and offset — all optional, combined with AND.

status is a JIRA/Bugzilla-shaped funnel, not the coarser set an earlier version of this table used:

submitted → pending → in_review → in_progress → done
                                                → wont_fix

resolved_at only means done

Moving a report to done stamps resolved_at; moving it to anything else (including wont_fix) clears it. wont_fix is a closed state, not a fixed one — the two aren't the same claim.

POST .../github-issue is the one action gated to the admin role specifically rather than any signed-in staff account — it reaches a third party and leaves a permanent public trace, unlike triaging a status. It formats the report as a real issue body, reading like a detailed report a person actually filed rather than a raw data dump: a Description section, an Environment table (platform, severity with a colored emoji, source — distinguishing an automatic MetricKit crash from one a named staff member filed manually, app/OS version, device model, reported-at, and a device correlation id when present), a collapsible stack trace, and a collapsible Additional Metadata block whenever the report carries any. The footer links back to the report in the dashboard when DASHBOARD_URL is configured. It writes the resulting github_issue_number / github_issue_url back onto the row, and a report that already has one refuses with 409 Conflict rather than opening a duplicate. Needs GITHUB_TOKEN (a PAT with Issues: write on GITHUB_REPO) configured on the backend — unset, this one endpoint fails with a clear error and everything else keeps working. DASHBOARD_URL is optional too; unset, the issue is just missing that one link.

POST (file by hand) takes the same body as the public submit endpoint above, but sets source: "manual" and reported_by to the caller instead of source: "app" — the distinction that lets the dashboard tell "the app reported this itself" from "a person typed this in."

GitHub status sync

Once a report is published, its status stays in sync with the linked issue in both directions — nobody has to remember to check GitHub by hand.

Dashboard → GitHub. PATCH .../crash-reports/{id} with a status, on a report that has a linked issue, also updates the issue: done closes it as completed, wont_fix closes it as not planned, any of the other four statuses reopens it if it was closed. Best-effort — a GitHub API hiccup logs a warning and never blocks the dashboard-side status change that triggered it.

GitHub → dashboard.

POST /api/v1/webhooks/github — no bearer token, verified by signature instead

A repo webhook (Settings → Webhooks → Payload URL https://api.truelabel.fun/api/v1/webhooks/github, content type application/json, subscribed to Issues only) authenticated via X-Hub-Signature-256 — HMAC-SHA256 over the raw body, keyed by GITHUB_WEBHOOK_SECRET. Unset, the endpoint refuses every delivery; there's no way to trust an unsigned one. Closing an issue on GitHub maps to done (or wont_fix if closed as "not planned"); reopening maps to in_progress. Every other event — ping (sent the moment the webhook is saved, and on every manual redeliver), and anything on an issue that isn't one of ours — is a silent 200, not an error, since this webhook fires for every issue in the repo, not just crash reports.

Why this can't loop

The webhook handler never calls the GitHub API — it only ever writes to the database, through a code path with no reference to GitHubService in scope at all. The outbound half above lives entirely in the dashboard's own PATCH handler. Two one-directional paths sharing a table, not a literal round trip.

Team

GET    /api/v1/admin/team                    — any signed-in staff account
PATCH  /api/v1/admin/team/{id}/role           { role: "admin" | "member" }        — admin role only
PATCH  /api/v1/admin/team/{id}/password       { new_password }                    — admin role only
PATCH  /api/v1/admin/team/{id}/permissions    { can_edit_products: boolean }      — admin role only
DELETE /api/v1/admin/team/{id}                                                    — admin role only

Inviting a teammate is just the same POST /api/v1/admin/auth/register used for the very first account, called with an existing admin's own bearer token attached — see Authentication → Dashboard staff accounts.

[
  { "id": "…", "name": "Tarun", "email": "…", "occupation": "SDE", "role": "admin", "can_edit_products": false, "created_at": "…" }
]

Changing a role refuses with 409 Conflict if it would demote the last remaining admin — otherwise the team could lock itself out with no way back short of a direct database edit. Removing a teammate has the same last-admin guard, plus a self-removal guard (409 Conflict either way) — nobody can remove their own account. crash_reports.reported_by already references dashboard_users(id) ON DELETE SET NULL, so a removed account's past reports and audit-log entries stay readable; the audit log also keeps a denormalized name snapshot for exactly this case.

can_edit_products is the one thing role doesn't already cover: an admin can edit any product regardless of this flag, but a member needs it set before PATCH /api/v1/admin/products/{id} accepts anything from them — see Products. It never grants the separate /verify action, which stays admin-only.

Resetting a password takes no current-password check — the caller's own admin session is the authority, same posture as changing a role. For a locked-out teammate, not for resetting your own (that's the self-service endpoint above, which does check it). Doesn't invalidate the target's existing session token; they stay signed in on whatever device they're already on, and just need the new password next time they log in elsewhere.

Activity

GET /api/v1/admin/activity — admin role only. Query: action?, target_type?, limit, offset

Who changed what: role changes, password resets, invites, removals, crash report status changes (dashboard-initiated or synced in from a GitHub webhook — actor_name: "GitHub", actor_id: null for the latter), publishing to GitHub, and product edits/verifications. Admin-only to view — tighter than crash reports' "any signed-in staff," since this surfaces password resets and role changes. actor_name is a snapshot taken at write time, not a live join, so a removed teammate's history still reads correctly.

Products

GET   /api/v1/admin/products              — any signed-in staff account
GET   /api/v1/admin/products/{id}         — any signed-in staff account
PATCH /api/v1/admin/products/{id}          — admin role, or can_edit_products
POST  /api/v1/admin/products/{id}/verify   { verified: boolean } — admin role only

GET (list) takes q (matched against product name, brand, and barcode, case-insensitively), country, verified, category, limit (default 50, max 200), and offset. Returns full product rows — not the lighter card shape the public consumer endpoints return — since editing needs full detail.

PATCH is a curated subset of the product record, not every column: name, brand, category, ingredients, allergens, image URL, quantity, nutrition facts, additives, NOVA group, Nutri-Score grade, and the three vegan/ vegetarian/palm-oil-free flags. Not editable here: barcode (identity, not a correction), source, and every field Open Food Facts sync owns or derives (off_synced_at, completeness, nutriscore_score, ecoscore_grade, crowd-verification counters, and a few tag arrays cut for now — see the backend's AdminUpdateProductRequest for the exact list). allergens on the wire writes to the structured allergens_tags column, not the legacy free-text one — the public API prefers the structured column whenever it's present, so editing the text column would silently have no visible effect for most (Open Food Facts-sourced) products.

Cache invalidation

Product reads are cached (see Rate Limiting for the broader caching picture). Both PATCH and POST .../verify invalidate the affected product's cache entry before returning, the same two keys the crowd-verification path already busts on a write — otherwise a correction wouldn't be visible to users for up to the cache's TTL.

verified is deliberately not part of the general PATCH — it's its own admin-only action, on its own route, the same shape as crash-reports' github-issue being separately gated next to the open-to-any-staff PATCH. It sits alongside the existing crowd-verification path (three matching crowd submissions auto-verifies a product), not replacing it — this is a manual, authoritative override an admin can also use to reverse a mistaken verification, which the crowd path has no way to do.

On this page