Admin API — Route Role Map

Role model — what each scope covers

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.

Writes to a user's account and internal balances (not real money movement): notes/tags CRUD, chat moderation, user update (roles/status/notes), ban/unban/bulk-ban, user state changes, KYC decisions, RG limits, password reset, reset TOTP, level recalculation.
Also covers crediting user balances: awarding bonuses, granting cash/packages, crediting redemption codes, awarding SW packages, awarding tournament prizes, and confiscating balances. These affect internal balance only — real money leaves the platform through payouts, gated separately by payments_write.

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).

Writes on catalog/content: create/update/delete for everything above. Plus multiplayer hash generation and S3 presigned URL for asset uploads.

The dedicated finance surfaces where real money is tracked: payouts and invoices (lists, details, counts).

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).
Balance credits (bonuses, grants, code redemption, SW package awards, tournament prizes) are not here — they only affect internal balances and must be confirmed through the payout flow to leave the platform.

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

Not a scope — routes tagged any only require a valid admin session: login, logout, health checks, and self-MFA setup (own TOTP activation and verification).

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

PATCH /users/:id — payload can change roles (privilege escalation vector).
GET /global-config — payload may contain secrets.
POST /confiscations — irreversible balance seizure.
POST /invoices/recalculate-tax — bulk across all invoices.
POST /user-levels/recalculate — bulk recompute across all players.
POST /user-limits/:userId/reset — RG compliance implications.
POST /multi-player-hashes/generate — affects game-outcome integrity.
DELETE /totp — resetting another user's MFA is an account-takeover vector.
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, not payouts, but abusable at scale.

Balance credits vs. payments: bonuses, grants, code credits, SW package awards, tournament prizes, and confiscations sit under user_administration_write because they only change internal balances. Real money in/out is gated separately by payments_write (payouts + invoices only).
Wallet / Wallet Transaction / Bet Wallet Transaction / Wager / Bet reads → user_administration_read (surfaced on User Detail). If your Payments team also needs standalone access, either grant both scopes or split.
Audit Log → user_administration_read. Could arguably be its own compliance_read scope.
Global Config read → platform_setup_read. If it contains real secrets, promote to a dedicated platform_secrets_read.
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 assumed self-only. If any take a target user ID, they should require user_administration_write.