> For the complete documentation index, see [llms.txt](https://docs.xyb.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyb.co/xyb-console/access-and-permissions-overview.md). # 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: ``` / ``` For example: `pay-invoice-svc/invoice_w` The code ends in a suffix that tells you what kind of access it grants: | Suffix | Meaning | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `_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: 1. **Identify the job function** (e.g. "Reconciliation Ops") and what it actually needs to do read invoices? Approve payments? Configure products? 2. **Check whether existing permissions cover it.** Most core permissions already exist per service. 3. **Create custom permissions only for gaps** a genuinely new capability that doesn't map to an existing one. 4. **Build a role** that bundles exactly the permissions that function needs no more. 5. **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)? 6. **Assign the role**, not individual permissions, to people. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.xyb.co/xyb-console/access-and-permissions-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.