User Roles & Permissions¶

Send Workbench uses a role-based access control model to determine what each user can see and do within the platform. Roles are defined in the client config repository, users are provisioned via the client's identity provider (typically Azure Active Directory), and authentication is handled through AWS Cognito using OpenID Connect.

This page explains where roles live in the client config, how the mapping from an IdP group to a Workbench role works, and how authority limits and personal preferences interact with the roles model.

Authentication overview¶

Authentication in Workbench follows a two-step flow:

Identity — the user signs in via the client's IdP (typically Azure Active Directory). The IdP provides their identity (email, name, group memberships).
Session — AWS Cognito (OpenID Connect) issues a JWT token that Workbench services use to verify the user's identity and mapped roles on every API call.

You do not configure the IdP or Cognito directly as a Workbench implementer — user provisioning is handled by the client's DevOps or platform team. What you control as a configurator is how Workbench roles are defined in the client config repository and which IdP group each role is mapped to.

Role definition files¶

Roles are defined per environment in:

config/{client}/role/{environment}/{environment}-roles.json

The base repository ships role/development/development-roles.json and role/production/production-roles.json. If your client uses UAT, create role/uat/uat-roles.json alongside these.

Each file is a JSON array of role definitions. The verified shape in the base repository is:

[
  {
    "mappedName": "SENDUK_UW_DEV",
    "name": "UW",
    "description": "Underwriter"
  },
  {
    "mappedName": "SENDUK_DOC_ADMIN_DEV",
    "name": "DOC_ADMIN",
    "description": "Document Admin"
  }
]

Field	Description
`mappedName`	The identifier of the IdP (e.g. AAD) group that this Workbench role is bound to. Users belonging to this group inherit the role.
`name`	The Workbench-internal role name, referenced throughout the rest of the config.
`description`	Human-readable description shown in admin tooling.

Role definitions in this file are intentionally simple — they map an IdP group to a Workbench role name. Permissions are not declared inline here; they are derived from the role name and from separate business class / feature configuration (see below).

Complete role reference¶

The following are all valid platform role name values, derived from the UserRole enum in the platform source. Only use values from this list — a role name that does not match will silently have no effect.

Core underwriting roles:

Role `name`	Purpose
`UW`	Underwriter
`UWA`	Underwriting Assistant
`UWT`	Underwriting Technician
`RO`	Read-only access

Admin and operations roles:

Role `name`	Purpose
`DOC_ADMIN`	Clause library / document admin
`DOC_SECURITY`	Document security admin
`PRICING_ADMIN`	Pricing admin
`USER_ADMIN`	User management
`SUPER_ADMIN`	Platform super admin
`GENERAL_OPS`	Operations team
`CSR_ADMIN`	Customer service admin
`CREDIT_CONTROL`	Credit control team
`ACTUARY`	Actuarial team

Financial Crime / Sanctions:

Role `name`	Purpose
`SC_FC`	Financial Crime team
`SC_FC_OPS`	Financial Crime team — ops variant

Smart Submissions:

Role `name`	Purpose
`SMART_SUBMISSION_ADMIN`	Smart submission admin
`TRIAGE_OPS`	Triage operations

Rules engine:

Role `name`	Purpose
`RULE_PARAMETER_ADMIN`	Rules engine parameter admin
`RULE_PARAMETER_START_DATE_ADMIN`	Rules engine start date admin

Fac RI:

Role `name`	Purpose
`FAC_RI_ADMIN`	Facultative RI admin
`FAC_RI_UW`	Facultative RI underwriter

DUA / Reporting:

Role `name`	Purpose
`BC_DA`	DUA reporting
`BC_PV`	Portfolio view
`PV_TEAM`	Portfolio view team

Other platform roles:

Role `name`	Purpose
`FTS_EDIT`	Full text search edit
`FTS_READ`	Full text search read
`JRI_ADMIN`	JRI admin
`SEND_CONNECT_ADMIN`	Send Connect admin
`SEND_CONNECT_DEV`	Send Connect developer

READ_ONLY is not a valid role name

The correct read-only role name is RO, not READ_ONLY. Using READ_ONLY will silently fail — users will not get the intended role.

UWM is not a platform role

There is no UWM (Underwriting Manager) role in the platform source. Underwriting manager permissions are typically handled through a business-class role or authority limit configuration, not a separate platform role. Confirm the pattern for your client with your delivery lead.

Business class roles: Access to specific lines of business is controlled by a separate, per-class role. The naming convention in the base repository is BC_{businessClassCode} — for example, BC_AH for Accident and Health, BC_AV for Aviation. Users need the relevant BC_* role to see and act on risks in that business class.

Some client implementations use a slightly different per-class pattern (e.g. {client}/{businessClassCode}/{environment}). Use whichever convention your client has adopted and confirm with your delivery lead.

How roles are referenced elsewhere in config¶

Role name values are referenced from several other parts of the config — for example:

be_config.json — assignableRoles lists the role names that can be assigned to tasks and risks within this client (e.g. SC_FC, SC_FC_OPS, DUA_TEAM, FINANCE_TEAM, CLAIMS_TEAM).
Risk actions — may restrict operations to specific roles (check defaultOwningRole or similar fields on the active core platform version).
Task templates and screens — role checks can gate visibility of tasks and fields.

Confirm the exact fields that accept role names on your active core platform version before adding new role references.

Adding a new role¶

Add an entry to each environment's role file (role/{environment}/{environment}-roles.json) with the correct mappedName for that environment's IdP group.
Ensure the corresponding IdP group exists and has the right users — this is a DevOps / platform team task.
Reference the role name in the relevant part of the config (e.g. a business class role, an action restriction, or an assignableRoles entry in be_config.json).
Raise a PR, have it merged, then raise a Client Build & Deploy (Dev) or Deploy Client Microservice Version (SIT/UAT) request in the Send Partner Portal.
Workbench picks up the change on its next periodic configuration refresh.

Warning

Duplicate role entries (same name across multiple JSON objects in the same environment file) can cause unpredictable behaviour — for example, a business class appearing twice in the UI. Check for existing entries before adding new ones.

Authority limits¶

The User Management service tracks per-user authority limits — the maximum premium value a given user is authorised to bind without escalation. Authority limits are stored in the user_authority_limit database table and can be managed via the Workbench admin interface.

Each authority limit record typically holds:

Field	Description
`authority_limit`	Maximum value (decimal)
`authority_type`	Type of authority (e.g. `PREMIUM`, `EPI`)
`business_class_type_code`	Which business class this limit applies to
`currency`	Currency of the limit
`status`	`ACTIVE`, `INACTIVE`, or `DELETED`

Authority limits feed into action prerequisites via the rules engine — an action can be configured to check the executing user's limit before it completes, preventing binding above the user's authority.

Dashboard filters and personal preferences¶

The User Management service also persists personal dashboard filter preferences per user. These allow users to save their own filtered views of the risk dashboard without affecting other users. These preferences are user-controlled and do not require configurator input.

User audit trail¶

All changes to authority limits and user status are recorded in a user audit table with:

The category of change (e.g. AUTHORITY_LIMIT, STATUS)
The original and updated values
The user who made the change and when

Practical guidance¶

When adding a new business class or placing type, remember to also add the matching business-class role (e.g. BC_{CODE}) to each environment's role file. Without this role, users will not be able to see risks of that class even if they hold other platform roles.

A useful pattern when onboarding a new line of business is to start by adding the role entries and deploying them first — this gives a user who can immediately access the new class during development while you build out actions, forms, and document config.