> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create/Edit Role

> The full-screen Create/Edit Role form under the merchant dashboard Settings > Team > Roles — set a role name and description, check permissions (view/edit, etc.) in the module-grouped permission list, and create or update a custom role.

## What this is

This is the full-screen form under **Settings > Team** in the merchant dashboard used to **create or update a custom role**. From the **Settings > Team** page, switch to the **Roles** tab and click **Add Role** in the top-right to open the **Create Role** page; clicking **Edit Role** on a role in the list opens the **Edit Role** page instead — both use the same form. Fill in the role's name and description on the left, and check the permissions this role should have in the module-grouped permission list on the right. Once saved, the role can be assigned to team members to control what they can see and do in the dashboard.

## Steps

Create a new role:

1. Go to **Settings > Team**, then switch to the **Roles** tab at the top.
2. Click **Add Role** in the top-right to open the "Create Role" full-screen page.
3. In the left **Role Details** section, fill in **Role name** (required, e.g. "Finance Manager", "Viewer"); **Description** is optional — a sentence explaining the role's purpose.
4. In the right **Permissions** section, check permissions module by module. Each module is a card; within a card, rows are grouped by resource, and each row is a set of action checkboxes (e.g. "View", "Edit"). Checking a box grants that permission.
5. Two **Select All** controls speed this up, with different scopes: the **Select all in this module** control at the top-right of each module card only checks the permissions you're allowed to grant **within that one module**; the page-level **Select All** in the top-right checks **every** grantable permission across **all modules**, and **Clear** next to it clears the selection (auto-included baseline permissions are retained).
6. The bottom of the page shows a live count, "{count} selected", under the role name. Once everything looks right, click **Create role** in the bottom-right. On success you'll see "Role created successfully!" and return to the Team page.

Edit an existing role:

1. In the **Settings > Team > Roles** list, find the target role and click its **Edit Role**.
2. The page loads that role's current name, description, and selected permissions (the top-left also shows a read-only **Role ID**).
3. Change the name, description, or add/remove permission checks.
4. Click **Save changes** in the bottom-right; on success you'll see "Role updated successfully!". Permission changes take effect for affected members **the next time they sign in**.

> The "x" or Cancel in the top-right closes the form and returns to the Team page without saving. Creating/editing a role requires the relevant role-management permission — the "Add Role" / "Edit Role" entry points are hidden without it.

## Fields and statuses

**Left "Role Details":**

| Field       | Meaning (merchant view)                                             | Notes                                       |
| ----------- | ------------------------------------------------------------------- | ------------------------------------------- |
| Role name   | This role's name, shown in the member list and when assigning roles | Required, up to 255 characters              |
| Description | A sentence describing what the role is for                          | Optional, up to 500 characters              |
| Role ID     | The role's unique identifier                                        | Shown only on the Edit Role page, read-only |

**Right "Permissions":** Permissions are grouped into cards by **module** — each card is a business area — and within a card, rows are grouped by **resource**, with each row a set of **action** checkboxes. **Which modules appear, and which resources/actions exist within each, are determined by the products enabled on your account** — the list you see may differ from other accounts. The table below shows possible modules that may appear (the grey subtitle text under each card title is in parentheses); it is not a fixed, exhaustive list:

| Module         | Card subtitle (as shown)                                 |
| -------------- | -------------------------------------------------------- |
| Payments       | Accept payments, manage refunds, disputes and settlement |
| Wallets        | Balances, transfers and FX operations                    |
| Global account | Global account and balance management                    |
| Payouts        | Initiate and manage payouts and recipients               |
| Conversions    | Perform currency conversions and manage FX               |
| Cardholders    | Manage cardholders and their profiles                    |
| Cards          | Card issuance, card programs and cardholder operations   |
| Crypto         | Crypto on-ramp and off-ramp operations                   |
| Treasury       | Treasury products, holdings and orders                   |
| Developers     | API keys, webhooks and OAuth apps                        |
| Settings       | Business profile, team, roles and other settings         |

**Action checkbox meanings** (the checkboxes that appear on each resource row — which ones appear depends on the resource):

| Action     | Meaning                                                          |
| ---------- | ---------------------------------------------------------------- |
| View       | Can view this resource                                           |
| Edit       | Can create/edit this resource                                    |
| Initiate   | Can initiate the operation (e.g. initiate a transfer or payment) |
| Close      | Can perform close-type operations (e.g. close an account)        |
| Cancel     | Can perform cancel-type operations                               |
| Export     | Can export (e.g. export reports, transaction details)            |
| Manage     | Can perform management-level operations on this resource         |
| Cardholder | Cardholder-related operations                                    |

**A few special states:**

* **Cardholder's "View/Edit" is checked by default and can't be unchecked** — this is a baseline permission every role automatically gets, part of "baseline permissions are included automatically."
* **A greyed-out, unclickable checkbox**: you don't hold that permission yourself, so you can't grant it to others (account Owners aren't subject to this). You can only grant permissions you yourself hold.
* **"{count} selected" at the bottom**: the total number of permissions currently checked for this role.

## Edge cases and troubleshooting

* **Can't see the "Add Role" / "Edit Role" entry point**: usually a missing role-management permission — ask your account admin or Owner to grant it.
* **Clicking "Create role" does nothing / prompts for a role name**: Role name is required — fill it in on the left first.
* **Worried that saving with zero permissions selected will fail**: generally no need to worry — every role automatically gets the Cardholder View and Edit baseline permissions and they can't be unchecked, so the permission set is never empty; you just add to it as needed.
* **Some permission checkboxes are greyed out and can't be checked**: those are permissions you don't personally hold, so you can't grant them to others — ask a member with higher permissions, or an Owner, to grant them.
* **Can't uncheck Cardholder View/Edit**: this is an automatically included baseline permission that every role has — that's expected.
* **Opening or refreshing the Edit Role page via a direct URL bounces you back to the Team page**: Edit Role must be entered by clicking "Edit Role" from the role list, not via a direct URL or refresh — go back to **Settings > Team > Roles** and click in again.
* **Changed role permissions but a member hasn't seen the change**: role changes take effect for that member **the next time they sign in**.
* **Save fails**: you'll see "Failed to create role", "Failed to update role", or a network error — retry later; contact support if it keeps failing.

## Common questions (Q\&A)

* **Q: How do I create a new role?** A: Settings > Team > Roles tab, click **Add Role** in the top-right, fill in a role name and description, check permissions by module on the right, then click **Create role**.
* **Q: Where do I change a role's permissions?** A: In Settings > Team > Roles list, click **Edit Role** on that role, add/remove permission checks, then click **Save changes**.
* **Q: Is the role name required? What about the description?** A: Role name is required (up to 255 characters); description is optional (up to 500 characters).
* **Q: How are permissions organized? How do I check them?** A: Grouped into cards by module; within a card, rows are grouped by resource, each with action checkboxes like "View/Edit" — check a box to grant it.
* **Q: How do I check all permissions for a module at once?** A: Click **Select all in this module** in that module card's top-right — it only checks the permissions you're allowed to grant within that one module; to check permissions across all modules at once, use the page-level **Select All** in the top-right, and **Clear** to reset it.
* **Q: Why are some permission checkboxes greyed out and unclickable?** A: Those are permissions you don't hold yourself — you can only grant permissions you already have (account Owners are exempt).
* **Q: Why can't I uncheck Cardholder View/Edit?** A: It's a baseline permission automatically included with every role — that's expected and can't be unchecked.
* **Q: Can I create a role with zero permissions selected?** A: You can't end up with "zero" — every role automatically gets the Cardholder View and Edit baseline permissions, which can't be removed, so the permission set is never empty. You add other permissions on top of that as needed.
* **Q: When do role permission changes take effect for a member?** A: The next time that member signs in.
* **Q: The Edit Role page bounced me back to the Team page after a refresh — what do I do?** A: Edit Role must be entered by clicking "Edit Role" from the role list — it can't be opened directly via URL or refreshed; go back to the list and click in again.
* **Q: Which module permissions can I see?** A: Depends on the products enabled on your account; common ones include Payments, Global account, Payouts, Conversions, Cardholders, Cards, Crypto, Treasury, Developers, Settings, and more.
* **Q: Can I change the Role ID?** A: No — Role ID is only shown, read-only, on the Edit Role page.