> For the complete documentation index, see [llms.txt](https://docs.artific.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.artific.nl/en/for-administrators/access/roles.md).

# Roles and rights

A role is a set of rights. Attach it to a group, and everyone in that group gets them. Found under **User management → Roles**.

## The two tabs

| Tab                    | What is in it                              |
| ---------------------- | ------------------------------------------ |
| **Organisation roles** | Roles your organisation created.           |
| **Artific roles**      | Standard roles provided with the platform. |

Standard roles cover the usual cases and are maintained for you. Start with them.

Typical standard roles include an organisation administrator role, a role for people who use assistants, and separate user and administrator roles for the AI Toolbox.

{% hint style="info" %}
Standard roles are read-only for customer administrators. If one is nearly right but not quite, create your own organisation role rather than asking for the standard one to change. It is shared across organisations.
{% endhint %}

## How a role is defined

A role has a **Name**, a **Description** and a grid of rights.

The grid has one row per area of the platform and one column per action:

| Action      | What it allows                                          |
| ----------- | ------------------------------------------------------- |
| **List**    | See that the items exist, in an overview.               |
| **Read**    | Open one and see its detail.                            |
| **Create**  | Make a new one.                                         |
| **Update**  | Change an existing one.                                 |
| **Delete**  | Remove one.                                             |
| **Execute** | Run or perform an action on one.                        |
| **Write**   | Write data, where an area distinguishes it from update. |

Rows cover the areas you would expect: assistants, chat sessions, themes, tools, the Toolbox and its elements and categories, knowledge sources and labels, the Inbox, users, groups, roles, organisations, secrets, reports and quality control.

Tick what the role should allow, then **Save role**.

## Reading the grid without getting lost

Two combinations account for most confusion:

* **List without Read.** People see a list of things they cannot open. Usually a mistake. Grant both.
* **Update without Read.** Effectively unusable, because they cannot open the thing they are allowed to change.

A workable rule: **List** and **Read** together for anything someone should see; add **Create**, **Update** and **Delete** only where they should change things; add **Execute** where they should run things.

## Creating a role

**Add new role** asks for a name and description, then opens the grid.

Two habits worth keeping:

**Start from nothing and add.** Ticking everything and removing what you do not want produces roles that quietly grant more than intended.

**Describe the person, not the ticks.** *"Builds and maintains assistants, but cannot manage users or organisation settings"* tells the next administrator what this role is for. *"Chatbot CRUD"* does not.

## Editing and deleting

Editing a role changes what everyone in every group carrying it can do, immediately. Check which groups use a role before changing it.

Deleting a role removes those rights from everyone who had them through it.

## Working out why someone cannot do something

1. Open the user and look at their **User groups**.
2. Open each of those groups and look at its roles.
3. Open those roles and find the row for the area in question.
4. Check the action they are trying to perform.

If the tick is missing, that is the answer. Add it to a role they already have, or add them to a group that has it, whichever fits your model better.