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
• Standard User
• Custom roles

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.