Admin API — Route Role Map

Role model — what each scope covers

Every scoped route's decorator is @Roles(<granular scope>, admin, super_admin), and authorization passes if the user holds any of those. The granular scope below is the lowest-privilege role that unlocks the route; admin and super_admin also unlock it.

user_administration_read

• Everything visible on a User Detail page: profile, KYC status, bans/state, tags, notes, limits, referrals, bonuses, codes, tournaments, statistics, wallets, transactions, wagers, bets.
• Also: audit log, external users list, list of pending password reset requests, and the payouts and invoices read surfaces (lists, details, counts) — the former payments_read scope has been folded in here.

user_administration_write

• Writes to a user's account that neither move money nor adjust balance: notes/tags CRUD, chat moderation, ban/unban/bulk-ban, user state changes, KYC decisions, RG limits, password reset, reset TOTP.
• Carve-outs: crediting or seizing balance now lives in funds_write, changing a user's roles field (on the otherwise user_administration_write route PATCH /users/:id) requires super_admin, and level recalculation moved to platform_setup_write.
• Target-level guard: several of these routes additionally refuse to act on a target user who is a super_admin unless the caller is also a super_admin (see Target-level protection).

funds_write

• Dedicated scope for any change to a player's in-game balance beyond low-value AMOE grants: awarding bonuses (POST /user-bonuses), granting cash and sweepstakes packages (POST /grants/grant-cash, POST /grants/grant-package), awarding SW packages (POST /user-sw-packages), crediting redemption codes (POST /user-codes/:id/credit), awarding tournament prizes (POST /user-tournament-prize-claims), and confiscating balances (POST /confiscations).
• These affect internal balance only — real money leaves the platform through payouts, gated separately by payments_write. Low-value AMOE grants are excluded (they don't require this scope), and bonus edits (PATCH /user-bonuses) are account maintenance rather than balance movements, so they remain user_administration_write.

platform_setup_read

• Reads on catalog/content: games, providers, sections, promotions, discounts, popups, tournaments, avatars, tags, levels, SW packages, notifications, whitelabel content, bonus templates, global config.
• Also holds document reads (see documents_write below).

platform_setup_write

• Writes on catalog/content: create/update/delete for everything above. Plus S3 presigned URL for asset uploads and user-level recalculation (POST /user-levels/recalculate) — treated as a platform-config recompute across all players. Multiplayer-hash generation has moved to super_admin.

payments_write

• Only actions that actually move money in or out of the platform: approve/deny/complete/fail payouts (bulk or single) and invoice adjustments (complete-underpaid, dismiss-underpaid, recalculate-tax). The payout/invoice read surfaces are now under user_administration_read.
• Balance credits (bonuses, grants, code redemption, SW package awards, tournament prizes) are not here — those live in funds_write, affect internal balances only, and must be confirmed through the payout flow to leave the platform.

documents_write

• Create/update/delete of legal & help documents. Read is granted via platform_setup_read because doc content is not sensitive; only mutations are.

admin

• Legacy blanket role, still present on essentially every route's @Roles(...) alongside the granular scope. Because the guard authorizes on any listed role, an admin can call every scoped route regardless of which granular scopes they hold.
• Exception: admin does not satisfy the two super_admin-only actions — generating multiplayer hashes (POST /multi-player-hashes/generate) and changing the roles field on PATCH /users/:id. It is also subject to the super-admin target guard.
• The granular-admin-roles migration keeps this role and backfills every existing admin user with all seven new granular scopes, so legacy admins keep full access.

super_admin

• Also a blanket role — listed on every scoped route, so it satisfies everything admin can, plus the two highest-blast-radius actions no other role grants: changing a user's roles and generating multiplayer game hashes (POST /multi-player-hashes/generate, which affects game-outcome integrity).
• It is the only role exempt from the super-admin target guard — a super_admin can ban/restrict/reset another super_admin.
• Field-level exception: on PATCH /users/:id the role gate is enforced per field — the route itself requires user_administration_write to edit status/notes, but a payload that touches the roles field escalates the requirement to super_admin (a privilege-escalation vector). It appears under both scopes in the table above for this reason.

Target-level protection — acting on super_admin accounts

• Independent of the route scope, a caller who is not a super_admin is refused when the target user is a super_admin. This guards account-takeover / lockout vectors and applies to: ban & unban (POST /user-bans, PATCH /user-bans/unban, and each item of POST /user-bans/bulk-ban), user-state changes (PATCH /user-states/:id, PATCH /user-states/user/:userId, and each item of PATCH /user-states/bulk-restrict), password reset (POST /password-reset-requests), and TOTP reset (DELETE /totp).
• In bulk operations the check runs per target, so super_admin targets are skipped/failed individually rather than blocking the whole batch.

any

• Not a scope — routes tagged any have no granular gate. Two flavours exist:
• Fully public (no auth): app info and health checks (GET /, /alive, /ready) and the login entry point (POST /auth/email/login).
• Any admin role (session must hold at least one admin role, but no specific scope): current session profile (GET /users/me), logout (DELETE /auth/logout), self-MFA setup (own TOTP activation and verification), and global-config read (GET /global-config), which the admin frontend needs to bootstrap.

Highest-blast-radius routes worth extra care

Gated by the roles above, but each deserves audit logging / secondary approval / rate limiting at the application layer:

• PATCH /users/:id — base route is user_administration_write, but a payload that changes the roles field is gated by super_admin (privilege escalation vector). Enforcement is field-level, so validation must inspect the payload rather than gate the whole route.
• GET /global-config — readable by any admin session (needed for FE bootstrap), so its payload must be scrubbed of secrets server-side.
• POST /confiscations — irreversible balance seizure.
• POST /invoices/recalculate-tax — bulk across all invoices.
• POST /user-levels/recalculate — bulk recompute across all players; now platform_setup_write.
• POST /user-limits/:userId/reset — RG compliance implications.
• POST /multi-player-hashes/generate — affects game-outcome integrity; now gated by super_admin.
• DELETE /totp — resetting another user's MFA is an account-takeover vector; a super_admin's TOTP can only be reset by another super_admin.
• PATCH /user-states/bulk-restrict, POST /user-bans/bulk-ban, PATCH /user-states — bulk account restrictions.
• POST /grants/grant-cash, POST /user-bonuses, POST /user-sw-packages, POST /user-tournament-prize-claims — balance credits (funds_write), not payouts, but abusable at scale.

Judgment calls worth reviewing

• Blanket admin roles: every scoped route still accepts admin and super_admin in addition to its granular scope, so the granular model is a minimum-privilege layer on top of a legacy hierarchy, not a replacement for it. If the intent is pure least-privilege, the blanket admin role would need to be removed from route decorators (and from users) rather than merely supplemented.
• Balance movements vs. payments: bonuses, grants, code credits, SW package awards, tournament prizes, and confiscations all sit under the dedicated funds_write scope. They only change internal balances. Real money in/out is gated separately by payments_write (payout + invoice mutations only).
• Payout / Invoice reads → folded into user_administration_read after the standalone payments_read scope was removed. If Finance needs read access without full user-admin visibility, reintroduce a dedicated read scope.
• Wallet / Wallet Transaction / Bet Wallet Transaction / Wager / Bet reads → user_administration_read (surfaced on User Detail).
• User-level recalculation → platform_setup_write, treated as a platform-config recompute rather than a per-user write.
• Audit Log → user_administration_read. Could arguably be its own compliance_read scope.
• Global Config read → any (any admin role), since the admin frontend needs it to bootstrap. Because every admin session can read it, any real secrets must be filtered out server-side (or moved to a dedicated scoped endpoint).
• S3 presigned URL → platform_setup_write. If documents editors upload attachments via S3, they'll also need this scope — consider granting documents_write holders a scoped variant.
• TOTP self-endpoints operate on the session user only. The DELETE /totp reset targets another user and is gated by user_administration_write plus the super-admin target guard.