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 passwordSelf-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 onlyGET (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_fixresolved_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 insteadA 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 onlyInviting 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, offsetWho 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 onlyGET (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.

