> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/getting-started/understanding-user-roles-and-permissions.md).

# Understanding User Roles and Permissions

{% hint style="info" %}
**Path:** View user roles at `/settings/user-management`
{% endhint %}

### Overview of User Roles

Harmony uses role-based access control (RBAC) to ensure that every team member only sees and interacts with what is relevant to their responsibilities. Roles are split into two types:

1. **Platform roles** - Apply across the whole tenant (Admin, Agent, Observer)
2. **Desk roles** - Apply per service desk (Manager, Agent, Observer)

Your effective access depends on the combination of these roles. Navigation, actions, and visible content all adapt to your assigned role automatically.

### Platform Roles

Platform roles are tenant-wide and control access to the main dashboard areas.

| Role                  | Access                                                                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Platform Admin**    | Full access: Dashboard, Tickets, Agents, Workflows, Assets, Software, People, Settings. Implicit access to all desks. Cannot be assigned to tickets unless also a Desk member. |
| **Platform Agent**    | All modules except Settings. The Tickets section is only visible if the user is also a Desk member.                                                                            |
| **Platform Observer** | Read-only access to the same areas as Agent. The Tickets section is only visible if the user is also a Desk member.                                                            |

Platform roles are assigned through your identity provider (e.g., Okta, Entra ID). Harmony reads them from your JWT on login.

{% hint style="info" %}
The Employee role has been removed from Harmony. Role assignment is now simplified to the platform roles listed above plus desk roles, reducing confusion when configuring access for your team.
{% endhint %}

### Desk Roles

Desk roles are per-desk and control what you can do on each service desk.

| Role              | Access                                                                        |
| ----------------- | ----------------------------------------------------------------------------- |
| **Desk manager**  | Manages the desk, its teams, and settings. Can access Settings for that desk. |
| **Desk agent**    | Works tickets on the desk.                                                    |
| **Desk observer** | Read-only access to the desk.                                                 |

You can have different desk roles on different desks. Platform Admins have implicit manager-level access to all desks.

### Understanding Role Permissions

Access is derived as follows:

* **Dashboard, Agents, Workflows, Assets, Software, People** - Visible only with a platform role.
* **Tickets** - Visible with a platform role combined with Desk membership, or any desk-level access.
* **Settings** - Visible to Platform Admins and desk managers (for their desks).
* **Landing page** - Platform role → Dashboard; desk-only → first desk; otherwise → Portal.
* **Assets** - Access to asset listings is governed by your role. Agents and users can only view the assets they are permitted to see, in line with Harmony's broader authorization model.

Desk access comes from your identity provider via groups. Your employee record is linked to desk resources with a `manager`, `agent`, or `observer` relation.

Permissions are applied uniformly across all Service Desk operations, so access control behaviour is consistent and predictable regardless of which service calls are made.

### Copilot Chat Access by Role

Harmony's Copilot chat is available to users with the following platform roles:

| Role                  | Copilot Access |
| --------------------- | -------------- |
| **Platform Admin**    | ✓              |
| **Platform Agent**    | ✓              |
| **Platform Observer** | ✓              |

Copilot is not available to users without a platform role (i.e., desk-only access). This means your support agents and observers can take advantage of AI-assisted guidance directly within their existing accounts, without requiring Admin-level access.

### API Access Keys and Role-Based Permissions

API Access Keys are subject to the same role-based permission boundaries as your human users. Each key is mapped to an equivalent platform role based on its permission level:

| Key Type         | Equivalent Role   | Capabilities               |
| ---------------- | ----------------- | -------------------------- |
| **Read + Write** | Platform Admin    | Full read and write access |
| **Read-only**    | Platform Observer | View-only access           |

This reduces the risk of over-privileged API access and makes it easier to enforce consistent security boundaries across both human users and automated integrations.

### Custom Display Names for Roles

You can rename roles in your workspace to better reflect how your team is structured. Instead of being limited to default role names, you can set a custom display name for any role - making it easier to align Harmony's access management with your organization's own terminology and hierarchy.

Role display names are also kept clear and consistent across Access Management, so permissions are easy to understand at a glance when assigning access to team members. No changes to underlying permissions occur when display names are updated.

### Viewing Your Assigned Roles

To see another user's roles, go to **Settings → User Management → Users**, then open the user. The detail view shows:

* **Groups** - IdP groups with role badges
* **Desks** - Desks with Desk manager / Desk agent / Desk observer badges

![User detail pane with Groups, Desks, and role badges](/files/PzE8HyQvcgvHmzFK5bGW)

Your own roles control what you see in the sidebar and where you land after login. There is no self-service "view my roles" page; admins manage roles in the identity provider.

### Understanding Role Badges

Role badges appear in:

* **Users table** - Under the Role column, showing platform and group-derived roles
* **User detail** - Next to each group and desk

Badges use outline style and show role names such as "Platform Admin", "Desk manager", "Desk agent", "Desk observer". If a custom display name has been set for a role, the custom name appears in place of the default.

![Users table with Role column badges](/files/rVhbcGkFdaqdZo4w71Nv)

### How Roles Affect Access to Features

| Feature   | Platform Admin                | Platform Agent      | Platform Observer  | Desk-only          |
| --------- | ----------------------------- | ------------------- | ------------------ | ------------------ |
| Dashboard | ✓                             | ✓                   | ✓                  | ✗                  |
| Tickets   | ✓ (all desks, if Desk member) | ✓ (if Desk member)  | ✓ (if Desk member) | ✓ (assigned desks) |
| Agents    | ✓                             | ✓                   | ✓                  | ✗                  |
| Workflows | ✓                             | ✓                   | ✓                  | ✗                  |
| Assets    | ✓                             | ✓                   | ✓ (read-only)      | ✗                  |
| Software  | ✓                             | ✓                   | ✓ (read-only)      | ✗                  |
| People    | ✓                             | ✓                   | ✓ (read-only)      | ✗                  |
| Settings  | ✓                             | ✓ (if desk manager) | ✗                  | ✗                  |
| Portal    | ✓                             | ✓                   | ✓                  | ✓                  |
| Copilot   | ✓                             | ✓                   | ✓                  | ✗                  |

### Group-Based Role Assignments

Roles are assigned through **groups** in your identity provider. Harmony does not edit roles directly; it consumes group membership and maps groups to platform and desk roles.

Admins configure role mappings in the identity provider. Changes there sync to Harmony and determine what users can see and do. You can also set custom display names for roles directly within Harmony's Access Management settings to match your organization's terminology.

{% hint style="info" %}
User and group management happens in your identity provider. Harmony reflects those assignments; it does not let you add or remove users or change their roles in the app.
{% endhint %}

***

### Related Resources

<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>User Management</strong></td><td>Manage users, groups, and roles</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/managing-user-management/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/managing-user-management/README.md</a></td></tr><tr><td><strong>Managing People</strong></td><td>Employee directory and profiles</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/managing-people/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/managing-people/README.md</a></td></tr><tr><td><strong>Managing Your Profile</strong></td><td>Update your profile settings and preferences</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/managing-your-profile-and-preferences/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/managing-your-profile-and-preferences/README.md</a></td></tr><tr><td><strong>Navigating the Interface</strong></td><td>Master the sidebar, command palette, and keyboard shortcuts</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/navigating-the-interface/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/navigating-the-interface/README.md</a></td></tr></tbody></table>


---

# 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.harmony.io/getting-started/understanding-user-roles-and-permissions.md?ask=<question>&goal=<endgoal>
```

`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.