Roles & permissions
The seeded roles, the permission catalogue, and how grants can be global or scoped to specific apps.
Access in the dashboard is governed by role-based access control. A user holds one or more roles; each role carries a set of permissions; each permission can be granted globally or scoped to specific apps.
Seeded roles
Five roles ship by default:
| Role | Intended for | Roughly can |
|---|---|---|
| Super Admin | Platform owners | Everything, including user management. Bypasses permission checks. |
| Admin | Operations leads | Manage apps, users, refunds; read everything. |
| Finance | Finance team | Refund approval, reports, reconciliation, transaction export. |
| Support | Support agents | Read transactions/refunds; initiate refunds within threshold. |
| Viewer | Read-only stakeholders | Read-only access to transactions and reports. |
You can also create custom roles (POST /admin/roles) composed from the
permission catalogue.
Permission catalogue
Permissions are resource:action keys. The read-only catalogue is available at
GET /admin/permissions. The ones you'll see most:
| Permission | Allows |
|---|---|
app:read / app:manage | View / register & configure apps and credentials. |
user:read / user:manage | View / create, enable, disable users and assign roles. |
payment:read / payment:export | Search transactions / export them as CSV. |
refund:read | Search refunds across apps. |
refund:create | Initiate a refund (and retry failed ones). |
refund:approve | Release an above-threshold refund to the gateway. |
report:read | Read reports and reconciliation. |
audit:read | Read the audit log, webhook delivery log, and callback evidence. |
Global vs app-scoped grants
A permission can be granted two ways:
- Global — applies to every application (e.g. read all apps' payments).
- App-scoped — applies only to named apps (e.g. approve refunds for app 5 only).
Cross-app search endpoints automatically narrow their results to the apps your grants cover. A Super Admin bypasses these checks entirely.
The system protects against locking yourself out: you cannot disable the last
Super Admin (LAST_SUPER_ADMIN_PROTECTED).
Sensitive actions
User management and other sensitive actions require step-up re-auth and are written to the append-only audit log.