Description

Purpose and use

Roles group permissions into assignable responsibilities so users receive the access they need for operations, administration, support, compliance, or customer activity without granting unrestricted access.

Who uses this. Administrators, security operations, compliance owners, and support leads use roles when granting, reviewing, or removing user access.

How it works. A role can be assigned to many users, and a user can hold multiple roles. RBAC and record-level permission checks use those assignments to decide which actions and records are visible.

What users do. Administrators create roles, update role descriptions, assign roles to users, remove stale assignments, and review errors when a role is still in use.

Outcomes and side effects. Role assignments change what users can see or do. They can affect customer data access, approval capability, configuration access, and operational controls.

Related manuals: Users, RBAC, RBAC Configurator, Profile.

Overview

The Roles API provides role-based access control (RBAC) functionality:

• Role management
• User-role assignments
• Permission management
• Access control

Who uses it: Platform and bank administrators use this API to define what actions different staff roles are allowed to perform, and to grant, change, or remove those roles for individual users. Onboarding and support flows also rely on it to assign a customer's default roles automatically.

Core Concepts

A user can have multiple roles. A role can have multiple users. each customer entry can have several own roles.

Roles

• Administrator, Internal, User — the three platform roles seeded on every installation (below)
• Customer-scoped roles (admin, executive, accountant, employee) — created per company, govern record grants inside that company
• Custom roles

Platform roles

Three roles are seeded on every installation — Administrator, Internal, User. They decide which operations a person may call. Which customer, account, or document the person may then see or change is decided separately by record-level permissions granted per customer (create, read, update, delete, read-all), so a platform role on its own opens no customer data. Use the descriptions below when raising or reviewing an access-rights request.

Read the tenant bundle before deciding. Everything below describes the default corebanq bundle. A role's operations are not a property of the role: each deployment ships its own data/rbac/*.rbac.yaml, and an operator can reassign any operation at runtime through the RBAC Configurator. The bundles already diverge — the activity feeds, for one, are seeded only in the axwis bundle. Always verify a grant against the bundle of the tenant in front of you before approving it.

The three roles are recreated at start-up if missing, but nothing stops their removal: the role API guards only against deleting a role that still has assignments, and never compares the name against the seeded three. A deleted default reappears at the next restart.

Rate limits are not a role property either. They come from the rate_limits app_config module keyed by role name, where -1 means unlimited; the default bundle sets -1 for Internal and Administrator and real caps for User. The whole mechanism is off unless rate_limits_switcher is enabled, and it ships disabled, so by default no role is rate-limited at all.

User

Purpose. The standard business role for every person who works with the platform on behalf of a customer company: account holders, company staff, signatories, anyone using the client application. It is granted automatically when a person registers or is invited to a customer, and is never assigned by hand. Staff of the institution carry it too when they came in through registration.

What it allows.

• Customer and company data: view and maintain the customer file, addresses, personas, signatories, links, preferences.
• Accounts: open, view, statements and balances, restrict and unrestrict, hold information.
• Payments: create and follow transfers, scan QR-bills, FX quotes and conversions on the customer's terms.
• Invoicing and counterparties: create, edit, list, send, download invoices; maintain counterparties and items.
• Onboarding and compliance self-service: KYB submission and status, KYC steps, document uploads.
• Collaboration and self-service: chats, notifications, activity feed, own profile, two-factor setup, own preferences.
• Reference data, read-only: countries, currencies, NOGA codes, the tariff that applies to the customer.
• Reading the role catalogue for its own customer, and its own role assignments.

Two of these are narrower than they look in the default bundle: the notification preferences and the v3 account-balance summary are seeded Administrator-only, and the activity feed is seeded only in the axwis bundle.

What it does not allow. The ledger, product and tariff configuration, operational scheduling, platform settings, and the administration application. Deleting accounts, customers, currencies, or countries, and administrative corrections of those records, sit outside the role.

Data scope. Only the customers on which the person holds record grants. A User with no grant on a company sees nothing of that company even though the operation itself is callable. Within a company the customer-scoped roles decide who holds which grants.

Limits. Seeded per-window caps, applied only when the rate-limit switch is on.

Request guidance. "User" alone is the normal ask for any customer-side person. The request must name the company the person belongs to and the customer-scoped role inside it; the platform role carries no customer data by itself.

Internal

Purpose. The back-office role for the institution's own staff: operations, finance, compliance, product owners, support. It gates the administration application — signing in there requires this role — and opens the operations that act on behalf of, or across, customers.

How it is granted. By an internal invitation, or by an existing holder assigning the role. Note that an internal invitation grants Internal plus the roles the invitation names, not User, even though the invitation email lists User among them. An operator invited this way does not hold the User-seeded operations, so anyone who needs both must be granted User explicitly.

What it allows, on top of whatever else the person holds:

• General ledger and books. The chart of accounts, ledgers and entries, journals, holds, balance history and snapshots, ledger-side completion of transfers, and reconciliation runs end to end.
• Products and tariffs. Create, edit, clone, and retire products and product rules, run and validate product logic, maintain tariffs and velocity rules, export tariff seeds, and review the subscription-charge queue.
• FX. Rate sources and rates, FX tariffs and spreads; set a customer's tariff and FX terms.
• Operations. Scheduled jobs (activate, trigger), run history, retry of subscription-billing charges and their attempt history.
• Customer administration. Correct, patch, or delete customers; delete accounts, addresses, KYB records, personas; correct transactions; patch transfers.
• Compliance. KYC screening, KYT records and provider callbacks, audit lookups.
• Roles. Maintain roles and user-role assignments, list users by role, change a user's role, delete users. In the default bundle /v1/roles and /v1/user-roles are seeded to Internal, so an Internal holder can create roles and assign any role, including Administrator, to any account — see the Administrator risk note below.
• Reference data. Create, edit, and delete countries, currencies, and items.
• Qualified signing. Signing-provider callbacks.

What it does not allow. Inviting users is not included: both invite operations are seeded Administrator-only, and the internal-invite handler additionally demands the Internal role, so that path needs both. Application configuration, licence information, risk definitions, and the fee-range, FX-fee, ops-run-detail and signing-diagnostic operations are Administrator-only in the default bundle as well.

Data scope. Record-level permissions apply to most operations, and operations that are not tied to a customer, such as the ledger, need no grant. There are exceptions where the role itself widens the scope: KYB treats an Internal holder as globally scoped, the recipients service returns deactivated recipients to Internal callers, and the activity feed treats Internal as staff. Do not assume record grants bound an Internal holder everywhere.

Limits. Unlimited in the default configuration.

Request guidance. Ask for Internal when the person needs the administration application or any area above. Name the area so the record grants can be scoped to it; Internal on its own opens no customer's data, and it does not carry User.

Administrator

Purpose. The platform-owner role. It exists to run and change the access-control and configuration machinery, and it bypasses record-level checks. It is not an extended Internal.

Who should hold it. A very small, named group: the platform administrators responsible for security configuration, and the system's own service account. The bootstrap administrator and the internal API user are created with Administrator plus Internal at first start.

What it allows. The role is added to every operation automatically, so it never has to be listed in a bundle. Two limits still apply: an unlicensed module is refused regardless of role, and signing in to the administration application requires Internal, which Administrator alone does not satisfy. Beyond what the other roles reach:

• Access control. Assigning and removing operations for roles, permission sync, export, and the review of unassigned operations. Four prefixes are hard-protected against reassignment in the Configurator — the endpoint-role API, roles, user-roles, and app-config administration — and only Administrator may be assigned there. The protection lives in the Configurator alone: the seed loader does not consult it, which is why the shipped bundle's Internal grants on roles and user-roles install unchallenged, and the remaining access-control operations are Administrator-only by seed convention rather than by guard.
• Platform configuration. Application-configuration entries and imports, licence information, supported languages.
• Compliance and risk. Crypto transaction screening and its poller statistics, risk-factor definitions and risk reports.
• Books and operations at the highest level. Ledger transaction listing and per-ledger balances, manual reconciliation matches and source deletion, cancel and resume of operational runs, retrieval of product logic by version, transfer event and status catalogues.

Second-factor recovery and user activation carry Administrator-only rows in the bundle, but those rows are never evaluated: the recovery operations are registered as public routes and the activation operations run under API-key authentication with no role check. Treat them as unauthenticated entry points protected by their token, not as administrator controls.

Data scope. Record-level checks are skipped for an Administrator on every customer, account, upload, and other record. Each bypass emits a structured administrator_bypass log line with the actor, record type, record, and permission — a log entry only. Nothing is persisted to the store the audit lookups serve, so these bypasses cannot be retrieved there after the fact.

Limits. Unlimited in the default configuration.

Risks to weigh before granting. The holder can change who may do what, alter platform configuration, and read or change any customer's data. Grant only with a documented owner, a review date, and a named backup. Note that in the default bundle the privilege gap to Internal is smaller than it looks: an Internal holder can already assign Administrator to any account, and the only Administrator-specific guard on assignments is a minimum-of-two check when one is removed.

Request guidance. An Administrator request must name the platform-administration duty that requires it (access-control management, application configuration). A request motivated by "needs to see everything" is answered with Internal plus read-all record grants instead.

Endpoints

Role Management

Create Role

POST /v1/roles

Create a new role. Role names must be unique — a request to create a role with a name that is already in use is rejected with a message explaining that the role already exists, rather than an unexplained failure.

Request Body:

{
  "name": "manager",
  "description": "Department manager role",
  "active": true
}

Get Role

GET /v1/roles/{role_id}

Get role details.

Update Role

PUT /v1/roles/{role_id}

Update role details.

Request Body:

{
  "name": "team_lead",
  "description": "Updated description for role",
  "active": false
}

Delete Role

DELETE /v1/roles/{role_id}

Delete a role. Roles with active user assignments cannot be deleted.

User-Role Management

Assign Role

POST /v1/user-roles

Create a user-role link. A user cannot be linked to the same role twice — assigning a role a user already holds is rejected with a duplicate-assignment message instead of an unexplained failure.

Request Body:

{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "role_id": "123e4567-e89b-12d3-a456-426614174001"
}

Remove Role

DELETE /v1/user-roles/{id}

Remove role from user.

Safeguards

These guardrails apply automatically and are not configurable per customer:

• Duplicate protection. Role names and user-role links must be unique. A duplicate request is rejected with a clear message instead of an unexplained failure, so an operator immediately knows the role or assignment already exists.
• In-use protection. A role cannot be deleted while it is still assigned to one or more users. The assignments must be removed first.
• Administrator lockout protection. Removing a user's platform-wide Administrator role is blocked if fewer than two active administrators would remain afterwards. This prevents an operator from accidentally locking everyone out of user and role management.

Error Responses

Errors return { "status": , "message": "" }. The API does not expose a separate machine-readable error code.