> 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/settings/managing-authorization-and-permissions.md).

# Managing Authorization and Permissions

How role-based access control works in Harmony: groups, permission sets, access levels and modules, and how to configure who can see and do what.

Harmony uses role-based access control (RBAC) so that every person sees only the parts of the product that matter for their job. An IT agent works tickets and devices, a procurement manager handles contracts, a security analyst reads everything but changes nothing, and employees use the self-service portal without ever seeing an admin screen.

All of this is configured in one place: **Settings → Authorization & Permissions**.

### How Permissions Work

The model has three building blocks:

| Building block      | Answers                                            | Where you manage it        |
| ------------------- | -------------------------------------------------- | -------------------------- |
| **Groups**          | *Who* gets access                                  | Groups tab                 |
| **Permission sets** | *What* a group can do: one access level per module | Permissions tab            |
| **Access levels**   | *How much* access: None, Viewer, Editor or Admin   | Inside each permission set |

Permissions are always granted to groups, never to individual people. To give someone access, put them in a group (or import the group they already belong to in your identity provider) and give that group a permission set.

![How groups, permission sets and levels combine into one person's access](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-6be9e3690a3d5feed25aa87e7a217640089b991a%2Fpermissions-model.svg?alt=media)

A few rules follow from this:

* **A person's access is the sum of their groups.** Someone in two groups gets everything both groups grant. For each module, the highest level wins.
* **Nothing subtracts access.** There are no deny rules. To take access away, remove the person from the group or lower the level in the permission set.
* **A group can hold several permission sets.** Combine a built-in set with a small custom one instead of copying everything into one large set.
* **Groups are the only link between people and permissions.** The Users tab is a read-only view that shows which groups give each person their access.

### Access Levels

Every module in a permission set is set to one of four levels. Levels are cumulative: Editor includes everything Viewer allows, and Admin includes everything Editor allows.

![The four access levels, from None to Admin](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-869c80d0261809d938682b6c2b6dd3ac3afd0355%2Faccess-levels.svg?alt=media)

| Level      | What it allows                                                                                                                                                                                                                                                                                                              | Typical use                                                            |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **None**   | Nothing. The module is hidden from the sidebar and from search, and its records cannot be opened by link. Where another module embeds data from it (for example a ticket's related devices), that section shows as a locked placeholder.                                                                                    | Everything a person does not need                                      |
| **Viewer** | Open the module and read all of its records, lists and details. Controls that change data are not shown.                                                                                                                                                                                                                    | Auditors, security and finance reviewers, managers who need visibility |
| **Editor** | Everything Viewer allows, plus day-to-day changes: create and update records, work tickets, assign devices, edit knowledge base articles. Sensitive actions are shown disabled, with a tooltip explaining why.                                                                                                              | Service desk agents, IT operations                                     |
| **Admin**  | Everything Editor allows, plus the sensitive actions: delete records, change the module's settings, edit purchase and financial details, run destructive device actions such as wiping a device or changing local admin rights, and run destructive identity actions such as password or MFA resets and account suspension. | Team leads, IT administrators                                          |

#### Dashboards

Dashboards have their own visibility on top of the level. A dashboard is either **public**, visible to everyone who can open the Dashboard area, or **restricted**, visible only to its owner, to the people it is shared with, and to Dashboard Admins. The workspace default dashboard is always public.

| Level on Dashboards | What it allows                                                                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Viewer**          | See every public dashboard, including the workspace default.                                                                                   |
| **Editor**          | Create dashboards. Edit and share public dashboards, including ones created by others. Other people's restricted dashboards stay out of reach. |
| **Admin**           | See, edit and share every dashboard, restricted ones included, and choose which dashboard is the workspace default.                            |

The person who created a dashboard can always view, edit, share and delete it, and anyone a dashboard is shared with can view it, even when it is restricted. Both still need at least Viewer on Dashboards to open the Dashboard area.

### Modules and Sub-Modules

A permission set lists every area of Harmony. Some modules are split into sub-modules so you can grant, for example, read access to applications but full control over contracts. Setting a level on a whole module applies it to all of its sub-modules.

| Module                     | Sub-modules                                                                                                                | Covers                                                                                                               |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Service Desk**           | Tickets, Conversations                                                                                                     | Tickets and the chat conversations behind them. The only module that can be limited to specific desks.               |
| **Application Management** | Applications, Contracts, Renewals                                                                                          | The software inventory with its owners and access; contracts and their documents; renewal tracking.                  |
| **Asset Management**       |                                                                                                                            | Devices and other assets, their owners, status and device actions. Admin here also manages the asset settings pages. |
| **Knowledge Base**         |                                                                                                                            | Knowledge base articles and their sources.                                                                           |
| **People**                 |                                                                                                                            | The employee directory and profiles.                                                                                 |
| **Dashboard**              | Dashboards                                                                                                                 | Custom dashboards and their widgets. Admin on Dashboards also chooses which dashboard is the workspace default.      |
| **Agents**                 |                                                                                                                            | AI agents, workflows and their runs. Also holds the **Trigger agents** capability (see below).                       |
| **Settings**               | General, Permissions, Service Desk Agent, Branding, Integrations, Secret Manager, Data Sets, Service Catalog, Broadcasting | Each settings page has its own sub-module, so you can hand out a single settings page without the rest.              |

{% hint style="success" %}
**Agents depend on other modules.** Agents read and change applications, devices, people and tickets. When you set Agents to Editor or Admin, Harmony lists what Agents needs (Applications Editor, Asset Management Editor, People Editor, and Tickets Editor on at least one desk) and offers to add the missing ones in one click. Lowering those permissions later may stop agents from working properly.
{% endhint %}

#### Capabilities

A few actions are **capabilities**: switches that sit under a module's rows in the permission set, separate from its access level.

| Capability         | Module | What it allows                                                                                                                         |
| ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Trigger agents** | Agents | Start agents through their triggers, such as an incoming webhook. It works on its own: a set can hold it with Agents left at **None**. |

Turn a capability on in the matrix when you create or edit a custom permission set. Its typical use is an [API key](https://docs.harmony.io/settings/managing-api-access-keys.md) that calls agent webhooks and nothing else.

#### What a Person Sees

* The sidebar shows only the modules where the person has at least Viewer on something. Settings appears for anyone who holds a Settings sub-module, and for module Admins who manage that module's settings pages.
* After signing in, a person lands on the first module they can open. Someone with no permissions at all lands on the self-service portal.
* Search results and navigation only offer modules the person can open.

### Built-In Permission Sets

Harmony ships six permission sets that cover the common roles. They are labelled **Default** in the Permissions tab, cannot be edited or deleted, and are identical in every workspace.

| Permission set        | Level  | What it grants                                                                                                                                               |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Platform Admin**    | Admin  | Everything, including Settings and permissions management.                                                                                                   |
| **Platform Operator** | Editor | View and edit the operational modules: Application Management, Asset Management, Knowledge Base, People, Dashboard and Agents. No Service Desk, no Settings. |
| **Platform Observer** | Viewer | Read-only access to the same operational modules.                                                                                                            |
| **Desk Manager**      | Admin  | Tickets and Conversations on every desk, including desks created later.                                                                                      |
| **Desk Operator**     | Editor | Work tickets and conversations on every desk.                                                                                                                |
| **Desk Observer**     | Viewer | Read-only access to tickets and conversations on every desk.                                                                                                 |

Combine them to cover a role. An IT generalist might hold **Platform Operator** and **Desk Operator**. For anything more specific, create a custom permission set.

### Limiting Service Desk Access to Specific Desks

Service Desk is the one module that can be scoped. In a custom permission set, **Manage desks** above the matrix lets you choose:

* **All desks**: every desk, including ones added later. This is what the built-in Desk sets use.
* **Specific desks**: pick desks from the list. Each selected desk gets its own Tickets and Conversations rows, so one set can give Admin on the IT desk and Viewer on the HR desk.

Sub-desks follow their parent desk.

### Access Everyone Has

Some access does not come from permission sets. These rules are always on, for every employee:

* **Their own tickets.** Anyone can view tickets they reported, created, are assigned to, are watching, or are asked to approve. Working a ticket as an agent still needs a Service Desk grant.
* **Their own devices.** People see the assets assigned to them. Unassigned devices that are in stock, and devices listed for sale, are visible to everyone so employees can pick equipment.
* **Their own profile.** Everyone can view their own People record.
* **Applications they own.** Application owners can view their application.
* **The self-service portal**, including the service catalog and the Harmony assistant, is available to every employee regardless of permission sets.

### Configuring Permissions

Open **Settings → Authorization & Permissions**. To open this page, a person needs at least Viewer on the **Permissions** row under Settings in their permission set; changing anything needs Editor or Admin. Platform Admins always can.

The page has four tabs:

| Tab             | What it shows                                                                                              |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| **Groups**      | Every group with its source, member count and permission sets. Create, edit and delete groups here.        |
| **Users**       | Every person who holds permissions through at least one group. Read-only.                                  |
| **Permissions** | The built-in and custom permission sets, with how many groups use each one.                                |
| **API keys**    | Keys that external systems use to call Harmony. Each key holds permission sets. See [API Keys](#api-keys). |

#### Create a Group

Click **Create group** and choose how its members are defined.

**Import from IdP** (recommended). The group mirrors a group in your identity provider, such as Okta or Microsoft Entra ID, connected through SCIM.

1. Pick the IdP group. The name is filled in for you; change it if you like, and add a description.
2. Choose **Include all members (full sync)** to keep the group identical to the IdP group, including people added later. Choose **Include specific members (opt-in)** to pick a subset; anyone who leaves the IdP group drops out of the Harmony group automatically.
3. Pick a permission set and click **Import**.

**Create manually.** You pick the members from the People directory yourself. Use this for small groups that do not map to anything in your IdP, or when SCIM is not set up.

1. Enter a name and a description.
2. Pick a permission set, or choose **Custom…** to build one for this group.
3. Select the members and click **Create**.

{% hint style="info" %}
Importing groups requires SCIM provisioning. Without it, Harmony offers manual groups only. The **Documentation** link at the top of the page opens the SCIM setup guide.
{% endhint %}

A group's source and sync mode are fixed once it exists; its name and description can be changed at any time. In a full-sync group the member list is read-only. Opt-in and manual groups have an **Add member** button.

#### Create a Custom Permission Set

1. Open the **Permissions** tab and click **Create permission**.
2. Enter a name and description, then click **Create**. The set is created empty and opens for editing.
3. In the matrix, choose a level for each module or sub-module. Rows left at **None** stay hidden from the group's members.
4. For Service Desk, use **Manage desks** to choose all desks or specific ones.
5. Click **Save changes**.

A new set applies to nobody until a group holds it.

#### Give a Group a Permission Set

1. Open the group from the Groups tab and switch to its **Permissions** tab.
2. Click **Add permission**, pick a built-in or custom set and click **Add**.
3. Repeat to add more sets. Members get the union of everything listed.

To take a set away from a group, click the trash icon next to it. The group's other sets are kept. You can also work from the other side: open a permission set, switch to its **Groups** tab and click **Add group**.

#### Edit a Permission Set

Where you start from matters:

* **From the Permissions tab**, editing a custom set changes it in place for every group that holds it.
* **From a group's Permissions tab**, Harmony protects the other groups. If the set is built-in, or is shared with other groups, saving creates a copy for this group and leaves the original untouched. If this group is the only one using the set, the set is updated in place. A note above the save bar tells you which will happen before you save.

#### Delete a Permission Set or a Group

* **Deleting a permission set** removes it from every group that holds it. The confirmation tells you how many groups lose the access it grants. Built-in sets cannot be deleted.
* **Deleting a group** removes the group and the access it granted. Members keep whatever their other groups grant. Nothing changes in your identity provider.

#### Check What a Person Can Do

1. Open the **Users** tab and search for the person.
2. The row shows their permission sets and how many groups they are in. Open the row to see every group, with its source and the permission sets it carries.

A person who is not listed has no permissions through any group. The usual reasons: they are not in an imported IdP group yet, they are in an opt-in group but were not picked, or the IdP sync has not run since they were added.

#### API Keys

API keys get their permissions the same way groups do: each key holds permission sets, built-in or custom. A key is authorized by its own sets only, never by the permissions of the person who created it. Changes the key makes are attributed to that person in activity history.

Viewing keys needs Viewer on the **Permissions** row under Settings; creating, rotating, deactivating and deleting them needs Admin. See [Managing API Keys](https://docs.harmony.io/settings/managing-api-access-keys.md) for the full guide.

### When Changes Take Effect

* Changes to groups, members and permission sets apply within seconds of saving. In rare cases they can take up to two minutes while caches refresh. Ask the person to refresh the page if they still see the old navigation.
* Changes made in your identity provider reach Harmony with the next SCIM sync, usually within a few minutes.

### Examples

| Goal                                     | Group                                                      | Permission sets                                                                                            |
| ---------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Help desk agents who also manage laptops | Import "IT Helpdesk" from the IdP, full sync               | **Desk Operator**, plus a custom set with Asset Management Editor, Knowledge Base Editor and People Viewer |
| A regional desk lead                     | Manual group with the lead                                 | Custom set: Service Desk limited to the "EMEA" desk, with Tickets Admin and Conversations Admin            |
| Procurement                              | Import "Finance" from the IdP, opt-in, pick the two buyers | Custom set: Contracts Admin, Renewals Viewer, Applications Viewer                                          |
| Security review, read-only               | Import "Security" from the IdP, full sync                  | **Platform Observer** plus **Desk Observer**                                                               |
| Workspace administrators                 | Import "IT Admins" from the IdP, full sync                 | **Platform Admin**                                                                                         |

### Troubleshooting

| Symptom                                                       | Likely cause                                          | What to check                                                        |
| ------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------- |
| A module is missing from someone's sidebar                    | No group gives them any level on it                   | Users tab → open the person → their groups and permission sets       |
| Buttons to create or edit are missing                         | Viewer level on that module                           | Raise the set to Editor, or add a set that grants it                 |
| A button is disabled with "You don't have enough permissions" | Editor level on an action reserved for Admin          | Raise the level to Admin if appropriate                              |
| A section shows "Restricted" with a lock icon                 | It embeds data from a module the person cannot open   | Grant Viewer on that module                                          |
| A person is not in the Users tab                              | They are in no group that holds permissions           | Import or create the group; for opt-in groups, add them as a member  |
| A person cannot be added to a group                           | Full-sync groups take their members from the IdP only | Change membership in the IdP, or use an opt-in or manual group       |
| A built-in set cannot be edited                               | By design                                             | Create a custom set, or edit from the group's page to get a copy     |
| Changes do not show for the person yet                        | Caches still refreshing                               | Wait two minutes and refresh the page                                |
| An administrator lost access to this page                     | Their group lost the Permissions row under Settings   | Someone else with Editor or Admin on the Permissions row restores it |

***

### 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>Managing Dashboard Access</strong></td><td>Public and restricted dashboards, sharing and ownership</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/managing-dashboard-access-and-permissions/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/managing-dashboard-access-and-permissions/README.md</a></td></tr><tr><td><strong>Managing Service Desks and Teams</strong></td><td>Desk structure, sub-desks and team configuration</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/managing-service-desks-and-teams/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/managing-service-desks-and-teams/README.md</a></td></tr><tr><td><strong>IDP Group Sync</strong></td><td>How groups and members arrive from your identity provider</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/idp-group-sync/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/idp-group-sync/README.md</a></td></tr><tr><td><strong>Managing API Keys</strong></td><td>Keys for integrations, automation and agent webhooks</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/managing-api-access-keys/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/managing-api-access-keys/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/settings/managing-authorization-and-permissions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
