Roles & permissions

Access to the dashboard is governed by role-based access control. An admin user holds one or more roles; each role bundles a set of permission keys; and each role assignment is either global or scoped to a single app (RBAC-4).

These endpoints are all admin-audience, session-authenticated — send your session token, never an API key:

-H "Authorization: Bearer SESSION_TOKEN"

All responses use the standard envelope. It is shown in full once below; afterwards only the data payload is shown.

{
  "data": null,
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:00:00Z" },
  "pagination": null
}

How a permission is resolved

A request's effective permissions are the union of the permission keys carried by every role the user is assigned, each tagged with that assignment's app scope. The seeded Super Admin role is special: a global Super Admin assignment bypasses every check, for every app.

Coarse method gating uses the permission key directly (@PreAuthorize("hasAuthority('user:manage')")). App-scoped checks additionally narrow to the apps the matching grant covers, so a cross-app search only returns rows from apps you can see — consistent with app isolation.

Seeded roles

Five system roles ship by default. They are marked system: true and cannot be deleted. The table below is the exact seed, rebuilt from migrations V2 (the first 14 permissions + the five roles), V20 (which added customer:read), and V23 (which added the six catalog permissions to Super Admin only).

Exact permission matrix

✓ = granted by the seed; — = not granted (a custom role can still add it).

Reading the matrix:

• Super Admin holds every key, and additionally bypasses all checks (so even a permission not in the catalogue would still pass for a global Super Admin).
• Admin is "everything except user:manage" — plus it never received the catalog keys, which V23 granted to Super Admin only. So Admin can approve refunds and manage apps, but cannot create users or manage products/benefits/subscriptions.
• Finance can move money (refund:create, invoice:create/void) and export, but cannot approve above-threshold refunds (refund:approve is Admin/Super Admin only).
• Support is read-only on payments, invoices, and customers.
• Viewer is read-only across payments, invoices, refunds, reports, and customers.

Permission catalogue

Permissions are resource:action keys. There are 21 in the catalogue, exposed read-only at GET /admin/permissions. Grouped by resource:

What each one allows:

Catalog permissions are Super-Admin-only by default

The six catalog keys (product:*, benefit:*, subscription:*) were added in migration V23 and, per PRD §6.1, granted to Super Admin only. No other seeded role — not even Admin — receives them out of the box. To let a Finance or Ops user manage products & prices, benefits, or subscriptions, create a custom role that includes the keys and assign it.

Global vs app-scoped grants

A role assignment carries an optional app scope (appScope):

• Global (appScope: null) — the role's permissions apply to every app.
• App-scoped (appScope: 5) — the role's permissions apply to app 5 only.

The same role can be assigned to one user multiple times with different scopes. A unique constraint prevents holding the same role twice at the same scope (global is folded so "global" can't be granted twice either).

Cross-app search endpoints automatically narrow their results to the apps your grants cover. A Super Admin assigned at global scope bypasses this narrowing and sees every app.

Managing the catalogue and roles

GET reads require user:read. Creating a role requires user:manage plus step-up re-authentication.

List the permission catalogue

curl http://localhost:8080/api/v1/admin/permissions \
  -H "Authorization: Bearer SESSION_TOKEN"

PermissionDto[]:

{
  "data": [
    { "id": 1, "key": "payment:read", "description": "View payments" },
    { "id": 6, "key": "refund:read", "description": "View refunds" },
    { "id": 8, "key": "refund:approve", "description": "Approve refunds above the per-app threshold" },
    { "id": 15, "key": "customer:read", "description": "View customer profiles and history" },
    { "id": 16, "key": "product:read", "description": "View products and their prices" }
  ]
}

List roles

curl http://localhost:8080/api/v1/admin/roles \
  -H "Authorization: Bearer SESSION_TOKEN"

RoleSummaryDto[]:

Get one role with its keys

curl http://localhost:8080/api/v1/admin/roles/3 \
  -H "Authorization: Bearer SESSION_TOKEN"

RoleDto:

{
  "data": {
    "id": 3,
    "name": "Finance",
    "description": "Day-to-day finance/ops: refunds and voids",
    "system": true,
    "permissionKeys": [
      "payment:read", "payment:export", "invoice:read", "invoice:create",
      "invoice:void", "refund:read", "refund:create", "report:read", "customer:read"
    ],
    "createdAt": "2026-01-04T09:00:00"
  }
}

Create a custom role

Requires user:manage + recent re-auth. The action is written to the append-only audit log as role.create.

curl -X POST http://localhost:8080/api/v1/admin/roles \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Catalog Manager",
    "description": "Manage products, benefits, and subscriptions",
    "permissionKeys": ["product:read", "product:write", "benefit:read", "benefit:write", "subscription:read", "subscription:write"]
  }'

CreateRoleRequest:

Returns 201 with the new RoleDto (system: false):

{
  "data": {
    "id": 6,
    "name": "Catalog Manager",
    "description": "Manage products, benefits, and subscriptions",
    "system": false,
    "permissionKeys": ["product:read", "product:write", "benefit:read", "benefit:write", "subscription:read", "subscription:write"],
    "createdAt": "2026-06-30T12:00:00"
  }
}

Failure cases:

Managing users, role assignments, and sessions

User management lives under /admin/users. Reads require user:read; every mutation requires user:manage plus recent re-auth, and is audited.

List / get users

curl "http://localhost:8080/api/v1/admin/users?page=0&size=20&search=ops&status=ACTIVE" \
  -H "Authorization: Bearer SESSION_TOKEN"

Query parameters: page (default 0), size (default 20), sortBy (default createdAt), order (default DESC), paginate (default true), search (optional), status (optional — e.g. ACTIVE, DISABLED). Returns paginated AdminUserSummaryDto[] (id, email, name, status, lastLoginAt).

GET /admin/users/{id} returns the detail AdminUserDto:

Each roles[] entry (UserRoleDto): id (the assignment id, used to revoke), roleId, roleName, and appScope (null = global).

Create a user

CreateAdminUserRequest:

curl -X POST http://localhost:8080/api/v1/admin/users \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Ops Lead",
    "password": "Sup3r-Str0ng-Passw0rd!",
    "roles": [ { "roleId": 2, "appScope": null } ]
  }'

Assign and revoke roles

Assign with POST /admin/users/{id}/roles. AssignRoleRequest:

# Grant role 3 (Finance), scoped to app 5 only
curl -X POST http://localhost:8080/api/v1/admin/users/42/roles \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "roleId": 3, "appScope": 5 }'

Revoke a specific assignment by its assignment id (the roles[].id from the user detail), not the role id:

curl -X DELETE http://localhost:8080/api/v1/admin/users/42/roles/8 \
  -H "Authorization: Bearer SESSION_TOKEN"

Both return the refreshed AdminUserDto. Revoking the last Super Admin assignment fails with 409 / LAST_SUPER_ADMIN_PROTECTED.

Disable / enable a user

curl -X POST http://localhost:8080/api/v1/admin/users/42/disable \
  -H "Authorization: Bearer SESSION_TOKEN"

Disabling immediately revokes the user's active sessions. Disabling the last active Super Admin fails with 409 / LAST_SUPER_ADMIN_PROTECTED. Re-enable with POST /admin/users/{id}/enable.

Revoke a session

user:manage holders can revoke any admin session by id. Revocation takes effect on the session's next request and is audited (session.revoke).

curl -X DELETE http://localhost:8080/api/v1/admin/sessions/777 \
  -H "Authorization: Bearer SESSION_TOKEN"

Returns 200 with data: null.

Sensitive actions: step-up & audit

The RBAC mutations are sensitive actions. Beyond the user:manage authority, they call requireRecentReauth(): if your session's last re-authentication is older than the configured window, the request is rejected with 403 / REAUTH_REQUIRED, and you must re-confirm your password before retrying. Each one also writes an entry to the append-only audit log.

Related