Roles & Permissions Overview - For Admins
Before you create a permission or build a role, it helps to understand how the two fit together and how they show up for your users once assigned. This page covers the concepts; the step-by-step guides for creating permissions and building roles are linked at the end.
The two building blocks
Permissions are the smallest unit of access. Each one grants a single, specific capability on a single service for example, the ability to view invoices, or the ability to edit a payment specification. On their own, permissions aren't assigned to people; they're assigned to roles.
Roles are named bundles of permissions that map to a job function: Treasury Analyst, Client Services, Auditor, and so on. You assign roles to employees, not individual permissions. This is what makes access manageable: instead of deciding "does this specific person get 40 individual permissions," you decide "which role does this person's job match," and the permissions come along with it.
A useful way to think about it: permissions describe what can be done; roles describe who gets to do it.
How permissions are structured
Every permission belongs to a service and follows the pattern:
<service-name>/<code>For example: pay-invoice-svc/invoice_w
The code ends in a suffix that tells you what kind of access it grants:
_r
Read: view data, no changes
_w
Write: create, edit, or perform an action
ui_r (occasionally mfe_r on older services)
Controls whether a menu item or screen is visible at all, separately from whether the underlying data can be read
That last one is worth pausing on, because it explains behavior your users will notice directly: a person can have ui_r for a section (so they see it in the navigation) but not have the _w permission for a specific action inside it — in which case the button is still visible, just disabled, usually with a tooltip explaining why. Conversely, no ui_r at all means the whole menu item disappears rather than showing up disabled. This is intentional and consistent across the platform, so once you know the pattern, permission-related UI behavior stops looking inconsistent and starts looking predictable.
Two kinds of permission
Most permissions are static a flat yes/no on a capability, like pay-invoice-svc/invoice_w.
Some are dynamic, meaning they're scoped to a specific resource or set of resources rather than being all-or-nothing:
For example: plt-workflow-svc/read@/family/** (read access to all workflow families) or cac-account-svc/read@/account/* (read access scoped to accounts). Dynamic permissions are how you grant access to a category or subset of resources rather than every resource a service manages.
One thing dynamic permissions are not: a way to gate access by a business value or threshold (e.g. "approve payments over $10,000"). That kind of rule lives in policy configuration elsewhere in the platform, not in the permission string itself.
How roles work in practice
When you build a role, you're choosing a set of permissions often spanning several services that together represent everything a job function needs and nothing it doesn't. A Payment Operations role, for instance, typically needs write access to payment entry, beneficiaries, and payment sessions, but should not include the permission to approve those same payments that belongs to a separate approver role.
That separation isn't just tidiness. It's the mechanism behind segregation of duties: keeping the person who initiates an action and the person who approves it as two different roles, so no single person can do both. The same logic applies elsewhere the team managing platform configuration typically shouldn't also hold payment or approval rights, and the team administering access and roles typically shouldn't be able to transact either. If you're designing roles for a regulated or higher-risk environment, it's worth explicitly mapping out which roles must never be held by the same person, not just which permissions each role needs.
Console roles vs. webapp roles
Roles come in two flavors, and they're not interchangeable:
Console roles are ones you create and manage yourself, for people using the admin console.
Webapp roles are fixed roles built into the platform for people using the customer-facing webapp (e.g. an "Admin," "CFO," "Treasury Manager," or "Owner" persona for the business using your banking product). These are pre-defined and can't be edited you assign them, but you don't customize what's inside them.
If you're trying to change what a webapp user can do, that's a different lever than editing a console role worth knowing before you go looking for an edit button that isn't there.
A note on sensitive permissions
Not every permission needs to live inside a standard role. Highly sensitive ones access to raw card details or PII that would normally be masked, for example are often deliberately left out of every role and instead granted only through a time-boxed, audited exception process when genuinely needed. If you have permissions like this in your catalog, it's worth deciding upfront that they're "break-glass only" rather than folding them into a role by default.
Putting it together
A rough mental checklist when setting up access for a new function:
Identify the job function (e.g. "Reconciliation Ops") and what it actually needs to do read invoices? Approve payments? Configure products?
Check whether existing permissions cover it. Most core permissions already exist per service.
Create custom permissions only for gaps a genuinely new capability that doesn't map to an existing one.
Build a role that bundles exactly the permissions that function needs no more.
Check for conflicts does this role, combined with any other role the same person might hold, cross a line you don't want crossed (e.g., maker + checker)?
Assign the role, not individual permissions, to people.
Last updated