Roles and permissions

Access control is two lists joined together. permission holds every key the platform knows about. role holds the named sets an operator can be put in. role_permission joins them.

Every account points at exactly one role through user.roleId. There is no per-user override, no second role and no inheritance between roles. Two people who need different access need two different roles.

The roles that ship

pnpm seed creates four roles and nothing else about them.

The first account is created only when the user table is empty, using SUPERADMIN_EMAIL and SUPERADMIN_PASSWORD from .env when they are set, and superadmin@example.com / 12345678 when they are not. A marker row is written into settings afterwards, so the seeder never re-creates that account on later updates — including after you delete it.

What Super Admin actually is

Super Admin does not hold all 715 keys. Every gate in the platform compares the role's name against the literal string Super Admin and returns true. Two things follow from that.

New permission keys shipped by an update work for Super Admin the moment they land. Every other role has to be re-ticked by hand, because a key that did not exist yesterday cannot have been granted yesterday.

The role is fenced off from the admin screens. It is excluded from the Roles list, so it cannot be edited or renamed there; it is excluded from the role picker on the Users screen, so nobody can be promoted into it; it cannot be deleted; and its permission set cannot be synced through the API. Super Admin rows are also hidden from the user list for everyone below Super Admin.

Only a Super Admin may create, rename or delete a role, or change which role an account sits on — and changing an account's role makes the caller re-enter their own password first.

Reading a permission key

A key is the admin route it guards, written as verb.domain.resource. Take the path, drop /admin, turn / into . and - into _, then prefix the verb.

Multi-word segments are snake_case, never kebab: forex_trading, trading_bot, ai.binary_engine, copy_trading. The resource is singular — tier, not tiers.

The verb says what the key lets you do.

715 keys in total, in the permissionsList array of backend/seeders/20240402234643-permissions.js. The routes between them demand 524 distinct keys across 1,168 declarations, and every one of those 524 is in the seeded list — so nothing a route asks for is ungrantable. The remaining keys gate screens and menu entries rather than API calls, which is why ticking a key is not by itself proof that a page will open.

access and view travel in pairs

Almost every admin screen is a data table, and a table asks two questions before it fetches anything: does this role hold the screen's access key, and does it hold its view key. Both must pass. The buttons are separate — create, edit and delete each default to hidden when the key is absent.

Where a grant is checked

The same key is consulted in four places, and they do not all matter equally.

Only the last one protects anything. The menu is presentation — a group header is shown when the role holds any of the permissions inside it, so seeing "Finance" in the nav says nothing about which of its twenty-two screens will open. One of those twenty-two, Trading Settings, declares no permission at all in frontend/config/menu.ts and has no URL-map entry either, so it is listed for every role that can see the group and opens on the access.admin fallback below. Hiding a menu entry is not a way to restrict access, and revealing one is not a way to grant it.

The URL map lives in frontend/middlewares/permissions.json and carries 245 entries. It fails closed: an admin path with no entry requires the base access.admin key.

Granting access

Recovering from a role with no permissions

You need a Super Admin to grant permissions, and a Super Admin has to be able to reach the admin panel. When neither is true — the only administrator sits on an empty role, or the Super Admin account was deleted — the way back in is the command line, on the server, with database access:

cd backend

# 1. Make sure every permission a route declares actually exists as a row.
#    Inserting one grants nobody anything; it only makes it assignable.
pnpm sync:permissions -- --apply

# 2. See what the role is missing, without changing anything.
pnpm sync:permissions -- --grant "Admin"

# 3. Hand them over.
pnpm sync:permissions -- --grant "Admin" --apply

Naming a role that does not exist prints the roles that do, with their ids — useful on its own when you are trying to work out which role an account is actually on.

The Permissions screen at /admin/crm/permission is read-only by design. It lists the keys and which roles hold them; there is no create, edit or delete, and the backend ships no route for any of those. Keys come from the seeder, not from operators.

Permission changes take up to a minute

The backend answers every gated request from an in-memory map of roles and their permissions. That map is refreshed on a 60-second timer, in every worker thread, so a grant or a revocation is in force platform-wide within a minute of the save — no restart.

The thread that handled your save reloads immediately, so the operator who made the change usually sees it at once. The other threads are what the timer is for: module state is per-thread, and reloading only the thread that took the POST would leave the remaining ones refusing at random, which looks intermittent and is worse to diagnose than a consistent delay.

The front end re-reads the role list on its own schedule — at most five minutes — so the menu and the URL gate can lag the API by a few minutes in either direction.

Notable permission groups

These are the keys worth deciding deliberately rather than ticking in bulk.

A separate Super-Admin fence sits behind edit.settings: the 39 keys in backend/src/utils/protected-settings.ts reject a save from any role but Super Admin, even one holding edit.settings. They are the two withdrawal-approval switches and the five withdrawal 2FA keys, the two P2P 2FA keys, the five TransFi ramp, custody and IBAN switches, the two transfer-fee keys and the transfer spread, the two demo-mode keys, the forex A-book routing switch, the trading-bot fee pair and its two kill switches, KYC feature enforcement, the nine AI Support keys, and the five DEX/Swap switches. Everything else on the Settings screen saves normally.

Extension admin sub-menus declare no permissions of their own. Their screens are gated by the URL map and by the API routes behind them, so an extension page that nobody mapped is reachable by anyone holding access.admin.

What updates do to your grants

pnpm seed — which pnpm updator runs on every update — is additive. The permissions seeder inserts only names that are missing; the roles seeder inserts only roles that are missing. Neither touches role_permission, so custom roles survive an update untouched.

Two repair seeders re-point grants when a key is renamed. They read the existing role_permission rows, insert the equivalent rows for the new key and only then remove the old one, so a role keeps the access it had rather than silently losing a screen. They are idempotent and safe to re-run.

API keys are a separate system

An API key carries scopes, not permission keys. The scopes are trade, futures, deposit, withdraw and transfer, plus three gateway.* scopes for the payment gateway extension, and they map to route prefixes rather than to the verb.domain keys above. Nothing on the Roles screen affects them.