Permissions

Before You Start

Read the following guides before proceeding:

Overview

Every corporation-scoped endpoint declares a set of permissions. The permission set in the caller's
corporation token is evaluated against that declaration before the handler runs.

The evaluation has three rules:

1. Su overrides everything. A holder of Su passes every endpoint, whatever it declares.
2. The declared permissions are alternatives, not a conjunction. Holding any one of them is enough.
3. An empty declaration admits any authenticated caller — any valid corporation token passes.

A caller that fails evaluation gets 403:

{
  "error_reason": "ErrorPermissionDenied",
  "error_description": "User does not have required permissions",
  "error_category": {
    "category": "CategoryForbidden",
    "http_status_code": 403
  }
}

A caller whose token carries an empty permission set, calling an endpoint that declares any permission,
gets 403 with User does not have any permissions.

Permissions are resolved at login and frozen into the token. Changing a role, or moving an
employee to a different role, has no effect until that employee logs in again.

Permission Codes

These are the names accepted by POST /api/v1/roles and PUT /api/v1/roles/{roleId}. The numeric code
is what appears as the key in the token's permissions claim.

TransactionView, AccountManage and CardView alone do not unlock any endpoint that the table below
does not list — they exist so a role can express read-only intent that future endpoints will honour.

Endpoint Permission Matrix

Anonymous — no token

Partner token

Corporation — profile and verification

Employees and roles

GET /api/v1/employees/{employeeId} declares no permission because a caller may always read their
own employee record. Reading anyone else's record requires Su, EmployeeSu, EmployeeManage or
EmployeeView, checked inside the handler.

Wallets and FX

Cards

Reading a 3DS request needs CardViewDetails; deciding it needs CardManage. A role that can see
pending challenges but not approve them is the default outcome — grant both if one employee is meant
to handle the whole flow.

Bank accounts and transfers

Recipients

Activity

Designing Roles

The permission model maps onto four operational areas — cards, employees, transactions, accounts — each
with its own *Su. A practical split:

Su is reserved for the on-chain owner. It is refused by POST /api/v1/roles and
PUT /api/v1/roles/{roleId} with 400 and Su permission is not allowed for custom roles.

Three endpoints require Su outright and cannot be delegated through a custom role:
POST /api/v1/corporations/verification-token, POST /api/v1/corporations/level-token and
POST /api/v1/wallets/global.