> For the complete documentation index, see [llms.txt](https://docs.in8sync.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.in8sync.com/client-admin-guide/managing-users/roles-and-permissions.md).

# Roles & Permissions

Manage the role library on a subsidiary — view, create, edit, and delete roles from the Modify Role dialog

A **role** sits between a user and their portal experience. It groups users together and links them to a workflow that defines what they see and can do.

```
User → Role → Workflow → Portal experience
```

The Modify Role dialog is where you manage every BRM role on the active subsidiary.

## When to use this

* Creating a new role before you assign it to users.
* Renaming an existing role or changing its branding overrides (logo, theme, default catalog).
* Removing a role that's no longer used.
* Confirming what roles exist before opening the Give Access flow.

## Before you start

* You need the **Client Admin** role.
* You're operating on the subsidiary in the top-bar selector. Switch first if you need to manage roles on a different subsidiary.

## Open Modify Role

Go to **User Management** in the sidebar and click **Modify Role** in the top-right. The dialog title reads **Modify Role** with the subsidiary name beside it.

![Modify Role dialog with four entity columns](https://229581143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAG04Mxmhw6PLRAZBvhtK%2Fuploads%2Fgit-blob-f0c764cb9eb36d258b41b6c6703c100126180925%2Fmodify-role-dialog.png?alt=media)

## How the dialog is organized

Roles are grouped into four entity-type columns shown side by side:

| Column       | Sub-groups                      |
| ------------ | ------------------------------- |
| **Employee** | Employee roles                  |
| **Customer** | Individual roles, Company roles |
| **Partner**  | Partner roles                   |
| **Vendor**   | Vendor roles                    |

Each role row shows:

* The role **name**.
* A **gear icon (⚙)** — opens **Edit Role**.
* A **trash icon (🗑)** — deletes the role. Only appears for custom roles.

### System roles vs custom roles

| Type       | Appearance         | Can delete? |
| ---------- | ------------------ | ----------- |
| **System** | Greyed out, italic | No          |
| **Custom** | Normal             | Yes         |

System roles ship with <code class="expression">space.vars.productName</code>. Custom roles are ones you've created. You can edit branding (logo / theme / default catalog) on either, but only custom roles can be deleted, and system role names can't be renamed.

## Create a role

Click the **+** button at the top-right of the entity-type column you want to add to. The **Add New Role** dialog opens.

| Field               | Notes                                                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Role Type**       | Only shown for the Customer column. Choose **Individual** (provisioned to a CustJob) or **Company** (provisioned to a Customer Contact). |
| **Role Name**       | The display name. Use something descriptive — *Store Manager — West Coast* beats *Role 3*.                                               |
| **Logo**            | Optional role-specific logo. Pick from existing files or upload. Leave blank to use the subsidiary's logo.                               |
| **Theme**           | Optional role-specific theme. Leave blank for the subsidiary default.                                                                    |
| **Default Catalog** | The catalog users with this role see by default. Leave blank for the global default.                                                     |

Click **Save** (or whatever the confirmation button on the dialog reads). The new role appears in its column and is immediately available in the Give User Access flow.

{% hint style="info" %}
The role's workflow is created at the same time as the role. To configure modules, layout, and behaviour, head to [Workflow Builder](/client-admin-guide/workflow-builder-overview.md) afterwards.
{% endhint %}

## Edit a role

Click the **⚙ gear** icon on any role.

| Field               | Notes                                                        |
| ------------------- | ------------------------------------------------------------ |
| **Role Name**       | Editable for custom roles. System roles can't be renamed.    |
| **Logo**            | Override the subsidiary logo. Leave blank to inherit.        |
| **Theme**           | Override the subsidiary theme. Leave blank to inherit.       |
| **Default Catalog** | Override the global default catalog. Leave blank to inherit. |

Save the dialog. Changes take effect immediately for every user assigned this role.

## Delete a role

Click the **🗑 trash** icon. Custom roles only.

{% hint style="danger" %}
Before deleting, **reassign every user holding this role** to a different role. Users left without a valid role lose access to their portal experience. Use the User Management table filtered by role to find affected users first.
{% endhint %}

## Change which role a user has

Creating roles and assigning them are two different jobs in the same dialog. To move an existing user onto a different role:

{% stepper %}
{% step %}

### Select the user

On the **User Management** page, tick the checkbox next to the user. You can select several at once to move them together.
{% endstep %}

{% step %}

### Click Modify Role

Then pick the new role for their entity type.
{% endstep %}

{% step %}

### Confirm

The change applies immediately. The user sees their new portal the next time they sign in or refresh.
{% endstep %}
{% endstepper %}

Assigning the wrong role is the most common reason someone reports seeing the wrong portal — it's worth double-checking straight after granting access.

## What success looks like

* The role appears in its entity-type column.
* It shows up in the role dropdown of the [Give User Access](/client-admin-guide/managing-users/give-user-access.md) dialog when you pick the matching entity type.
* Users assigned to it see the right portal experience after their next login.

## Common issues

* **The new role doesn't appear in Give Access** — check you picked the right entity type. The Add New Role button is column-specific.
* **A user complains the wrong logo / theme appears** — role-level branding overrides subsidiary branding. Clear the Logo / Theme fields on the role to fall back to subsidiary defaults.
* **The trash icon isn't visible on a role** — that's a system role. Only custom roles can be deleted.

## Best practices

* **Keep the role count manageable.** Five to ten roles covers most businesses.
* **Test before deploying.** Create a test user, assign the new role, log in, verify.
* **Review quarterly.** Remove roles that aren't in use; audit branding overrides.
* **Use branding overrides sparingly.** Subsidiary-level branding is easier to maintain. Reach for role-level overrides only when a role genuinely needs a different look.

## Related

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Give User Access</strong></td><td>Assign this role to a user.</td><td><a href="/client-admin-guide/managing-users/give-user-access.md">Give User Access</a></td></tr><tr><td><strong>Workflow Builder</strong></td><td>Configure the workflow this role links to.</td><td><a href="/client-admin-guide/workflow-builder-overview.md">Workflows</a></td></tr><tr><td><strong>How Access Works</strong></td><td>The four layers of access control.</td><td><a href="/client-admin-guide/managing-users/access-control.md">How Access Works</a></td></tr></tbody></table>