> For the complete documentation index, see [llms.txt](https://help.tellius.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tellius.com/tellius-6.4/settings/users-and-access/custom-roles.md).
# Custom roles
Create custom roles, set No Access, Read Access or Full Access for each module, assign roles to users and groups, check the access a user ends up with, and delete roles you no longer need.
A role decides which parts of Tellius a person can reach. Alongside the built-in roles, you can create your own roles and choose, module by module, what each one allows. For example, you can give one team Kaiya and nothing else, keep another team on Vizpads, or let builders create Missions and Apps while other people only view them.
You manage all roles on one page: **Settings → Workspace → Users & Access → Roles**. Built-in roles appear there too, so you can review and adjust them in the same place.
{% hint style="info" %}
Roles belong to the **Manage workspace** module, along with users and groups. To create, edit, assign or delete roles, your role needs **Full Access** to **Manage workspace**.
{% endhint %}
### **The Roles page**
The page lists every role in a table. Type in **Search roles** to find a role by name, or select the arrow beside **ROLE NAME**, **TYPE** or **DESCRIPTION** to sort by that column. Select **Create role** to add a new one.
| Column | What it shows |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **ROLE NAME** | The name of the role. |
| **TYPE** | **System** for a built-in role. **Custom** for a role someone in your workspace created. |
| **DESCRIPTION** | The one-line description given to the role, if any. |
| **MODULE ACCESS** | **All modules** when the role has no limits. Otherwise, the number of modules the role holds back, such as **3 restricted**. |
| **ASSIGNED TO** | How many users and groups hold the role. |
| **ACTIONS** | **Edit role** (the pencil) opens the role. **Delete role** (the trash can) removes it. See [Delete a role](#delete-a-role). |
### **Access levels**
For each module, a role holds one of three levels. Hover over the info icon beside each column heading in the role editor to see its definition.
| Level | What the user gets |
| --------------- | --------------------------------------------------------------------------- |
| **No Access** | The module isn't available to the user. |
| **Read Access** | The user can open and use content that already exists, but can't change it. |
| **Full Access** | The user can use everything the module supports. |
A module at **No Access** drops out of the user's navigation. A module at **Read Access** stays open for browsing, but the actions that create or change content are not offered.
### **Modules you can set**
The role editor groups modules under six headings. The table explains what each module covers.
| Group | Module | What it covers |
| ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Kaiya** | **Chat** | Asking questions about your data in plain language. |
| | **Apps** | Kaiya Apps that people build and share across the workspace. **Read Access** lets the user open and use Apps that already exist, and their data refreshes keep running. **Full Access** is needed to build an App in Kaiya chat, save a new version of it or change its code. Renaming or deleting someone else's App, and choosing or deleting its versions, works with **Full Access** to **Apps** or with **Content management**. |
| | **Missions** | Multi-step analyses that Kaiya plans and runs. **Read Access** lets the user open the Missions others build. **Full Access** is needed to create a Mission. |
| | **Context** | The skills and memories that shape Kaiya's answers, on the Context page. |
| | **Context Models** | Kaiya context models: the **Context Models** tab on the Data page, picking models in the chat, and the suggestions that improve them. **Read Access** lets the user open models and ask questions on them. **Full Access** also lets them create, edit, share, archive and delete models and decide suggestions, within each model's own access. See [Who can work with a context model](https://help.tellius.com/data/kaiya-context-model#who-can-work-with-a-context-model). |
| **Analytics** | **Vizpad** | Dashboards made of charts and filters. |
| | **Predict** | Training and applying machine learning models. |
| | **Insight** | Automated findings across a Business View. |
| | **Search** | Searching your data and saved content. |
| | **Feed** | Metrics and alerts that keep watch on your data. |
| **Projects** | **Projects** | Workspaces that bring content and the people working on it together. |
| **Collaboration** | **Sharing** | Giving another person access to a Kaiya chat, Vizpad, dataset or insight that you can already reach. |
| **Data** | **Datasets** | Datasets, their connections and the pipelines between them. |
| | **Business Views** | The modelled layer over datasets that charts, insights and Kaiya ask their questions of. |
| | **Data download** | Downloading all of the raw data behind a dataset or Business View. It does not control the **Export** button on a chart, Vizpad or insight. Those exports follow the user's access to that item. The built-in Interactive, Explorer, Discoverer, Explore & Discover and View roles have it at **No Access**. See [User roles and permissions](https://help.tellius.com/settings/users-and-access/user-roles-and-permissions). |
| | **Connect source** | Adding and setting up the sources that data comes from. |
| **Administration** | **Own settings** | The user's own profile, preferences and personal connections. |
| | **Manage workspace** | Users, groups, roles, data connections, schedules and monitoring. |
| | **Manage system** | Impersonation, connectors, backup and restore, system prompts and the runtime log level. |
| | **Content management** | Opening, editing and deleting anyone's Vizpads, datasets, insights, models, Kaiya chats, Apps and context models without being shared on them. It also lets the user open, but not change, anyone's Missions. This is the access the built-in Content Admin role has, offered as a level any role can hold. |
{% hint style="success" %}
**Apps and Missions: Read Access or Full Access?** Give **Read Access** to people who use the Apps and Missions that others publish, such as field teams or leaders who read briefings. Give **Full Access** to the people who build them. When someone whose role holds only **Read Access** asks Kaiya to build or change an App, Kaiya stops and says that their role doesn't include it, so they know to ask an administrator. In Kaiya chat, a card for an App or a Mission that the user's role doesn't include at all stays in the conversation and says so, in place of the button that opens it.
{% endhint %}
#### **Modules with two levels**
Some modules offer only **No Access** or **Full Access**. Their **Read Access** option is greyed out. These are **Sharing**, **Data download**, **Connect source**, **Manage workspace**, **Manage system** and **Content management**.
**Own settings** is fixed at **Full Access** for every role and can't be changed. Every user can always reach their own profile and preferences.
### **Modules that depend on other modules**
Some modules can't work without another one. When you raise a module that needs another, the editor raises the other module to the level it needs and locks the levels below it. A note under the locked module names that level and every module that needs it. For example, the **Business Views** row reads *Read only is required by Chat, Search, Feed*, and the **Chat** row reads *Full is required by Apps, Missions* when those modules are at **Full Access**.
| When you set this module | The editor raises this module |
| ------------------------------------------------------- | -------------------------------------------------- |
| **Apps** or **Missions** to Read Access | **Chat** to Read Access |
| **Apps** or **Missions** to Full Access | **Chat** to Full Access |
| **Context** to Read Access or Full Access | **Chat** to Read Access |
| **Context Models** to Read Access or Full Access | **Chat** to Read Access |
| **Chat** to Read Access or Full Access | **Datasets** and **Business Views** to Read Access |
| **Vizpad** or **Predict** to Read Access or Full Access | **Datasets** to Read Access |
| **Search** or **Feed** to Read Access or Full Access | **Business Views** to Read Access |
The rules follow the chain. Setting **Missions** to **Full Access** raises **Chat** to **Full Access**, and **Chat** in turn raises **Datasets** and **Business Views** to **Read Access**.
Keep in mind:
* **Only lower levels are locked.** A locked module can't go below the level it needs, but you can still raise it.
* **A rule limits only the module that is needed.** For example, **Missions** at **Read Access** with **Chat** at **Read Access** is allowed. That gives you a role that opens the Missions others build without full chat access. To let a role build Missions or Apps, both they and **Chat** need **Full Access**.
* **Lowering a module releases the lock.** If you set **Missions** back to **No Access**, **Chat** keeps the level it had, but you can now lower it. **Datasets** and **Business Views** stay locked for as long as **Chat** is above **No Access**.
* **Insight**, **Projects** and the two-level modules don't raise any other module.
* **Context Models** at **Full Access** still needs **Chat** only at **Read Access**. To let a role build context models in the chat, give it **Full Access** to **Chat** and **Datasets** as well.
{% hint style="warning" %}
**Roles saved before Tellius 6.4.** A custom role saved before Tellius 6.4 with **Search** or **Feed** turned on and **Business Views** at **No Access** keeps that setting until it is saved again. Its users see a message that their role does not include Business views access. Open the role and select **Save** to raise **Business Views** to **Read Access**.
{% endhint %}
### **Create a role**
Watch a one-minute walkthrough, or follow the steps below.
{% embed url="" %}
1. Go to **Settings → Workspace → Users & Access → Roles**.
2. Select **Create role**.
3. Enter a **Role name**. This field is required. Each role needs its own name, and capital letters don't count as a difference, so "Sales Analyst" and "sales analyst" can't both exist. While the name matches an existing role, **Create** stays unavailable.
4. Enter a **Description**, if you want one. A short line on what the role is for helps others pick the right role later.
5. Under **Module access**, choose **No Access**, **Read Access** or **Full Access** for each module. A new role starts with every module at **No Access**, so turn on only what the role needs. To set every module under a heading at once, choose a level on the heading row, such as **KAIYA**. A module that doesn't offer that level keeps its current one. When the modules under a heading hold different levels, the heading row shows no level selected.
6. Select **Create**. To leave without saving, select **Cancel** or **BACK**.
A role's module access can only narrow what the role is able to do. It never adds to it. You can also give a role only the access that you hold yourself. If you try to give more, Tellius refuses to save and the message begins *You cannot grant access you do not hold yourself*.
### **Edit a role**
1. Go to **Settings → Workspace → Users & Access → Roles**.
2. Select **Edit role** (the pencil) in the role's row.
3. The role opens with its name, its type (**System** or **Custom**) and the date it was last updated. It has two tabs: **Access** and **Assignments**.
4. On the **Access** tab, change the **Role name**, the **Description** or any module's level. A summary above the table counts how many modules are at each level, and it updates as you make changes.
5. Select **Save**. To leave without saving, select **Cancel** or **BACK**.
You can edit built-in roles in the same way. A change to a role applies the next time each user who holds it loads a page. They don't need to sign out and back in.
### **Assign a role**
You can assign a role to users and to groups. A group's role reaches every member of the group, on top of each member's own role. There are three places to assign a role.
#### **From the role**
1. Open the role and select the **Assignments** tab.
2. Select **Assign**. The **Assign this role** dialog lists users and groups. Anyone who already holds the role is left out of the list.
3. Type in the search box to find users and groups by name.
4. Select the check box beside each user or group you want. The dialog counts how many you have selected.
5. Select **Assign**. Select **Cancel** to close the dialog without assigning.
A user holds one assigned role at a time, so assigning a role to a user replaces the role they had before.
The **Assignments** tab lists everyone who holds the role, with the **Name**, the **Type** (**User** or **Group**), the **Details** (a user's email address) and the date under **Assigned on**. Use **All**, **Users** and **Groups** to filter the list. Each heading shows a count. Select **Remove** on a row to take the role away from that user or group.
#### **From the Users page**
1. Go to **Settings → Workspace → Users & Access → Users**.
2. Open the row menu for the user and select **Edit user**.
3. Choose the role from the **Role** dropdown. It lists custom roles alongside the built-in ones. The role you choose replaces the user's current role.
4. Select **Save**.
The Users table shows each user's role under **ASSIGNED ROLE**, and every role that gives them access under **ROLES IN EFFECT**. To list only the users who hold a particular role, choose it in the role filter above the table. The filter lists every role, custom roles included. For more on the Users page, see [Users](https://help.tellius.com/settings/users-and-access/users).
#### **From the Groups page**
1. Go to **Settings → Workspace → Users & Access → Groups**.
2. Open the group's menu and select **Edit**.
3. Choose the role from the **Add Role** dropdown. It lists custom roles alongside the built-in ones.
4. Select **Update**.
A group with no role shows **None** in **Add Role**. A group set to **None** adds nothing to its members' access. For more on groups, see [Groups](https://help.tellius.com/settings/users-and-access/groups).
{% hint style="warning" %}
New users are added to the default group automatically, and so are users who sign in through single sign-on for the first time. Whatever role the default group holds, every new user receives it. Check that role before you change the default group.
{% endhint %}
### **How access adds up**
A user can receive access from more than one place: their own role, plus the role of each group they belong to. For each module, Tellius uses the highest level the user receives. The levels rank from low to high: **No Access**, **Read Access**, **Full Access**. A **No Access** in one role never takes away access that another role gives.
For example:
| Where the access comes from | Vizpad |
| --------------------------- | --------------- |
| The user's own role | Read Access |
| Group A's role | No Access |
| Group B's role | Full Access |
| **What the user gets** | **Full Access** |
### **Check what a user can do**
The **Effective access** dialog shows the level a user ends up with for each module and the roles that give it. When a user holds a role and belongs to several groups, this is the quickest way to see what they can reach and which role to change.
You can open the dialog in two places:
* **For any user:** on the Users page, open the user's row menu and select **View effective access**. You need **Manage workspace** access to check someone else.
* **For yourself:** go to **My Profile** and select **View effective access** beside **Roles in effect**. **Roles in effect** lists every role that gives you something: your own, plus one for each group you belong to. You can always check your own access. See [My Profile](https://help.tellius.com/settings/my-profile-1).
The dialog shows:
* **A summary line:** how many modules there are, and a chip for each level, **Full**, **Read only** and **No access**, with the number of modules at that level. Select a chip to fade the modules at the other levels, so the ones at that level stand out. Select it again to show all modules evenly.
* **The modules, grouped by heading in two columns:** **Kaiya**, **Analytics** and **Projects** on the left, and **Collaboration**, **Data** and **Administration** on the right. Each module shows the level the user ends up with. **Context Models** is listed under **Kaiya**.
* **Where each level comes from:** point to a module, or move to it with the keyboard, to see how many sources grant it. The list names each source, the user's own role (marked **own role**) or a group, with the level it gives. When several sources disagree, the ones that set the level are marked **sets** and the others **overridden**, because the highest level wins. A long list ends with how many more sources there are.
The dialog is read-only. To change what a user can reach, change their role, their groups, or the roles those groups hold.
{% hint style="info" %}
**Track down unexpected access.** Select the **Full** chip to see at a glance what a user can change. Then point to a module that surprises you: the source marked **sets** is the role or group to change. Lowering a source marked **overridden** makes no difference, because another source already gives the same or a higher level.
{% endhint %}
### **Delete a role**
1. Go to **Settings → Workspace → Users & Access → Roles**.
2. Select **Delete role** (the trash can) in the role's row.
You can delete a role only when no user or group holds it. This applies to built-in and custom roles alike.
While a role is assigned, its **Delete role** icon is greyed out. Hover over the icon to see how many users and groups hold the role. To delete it:
1. Open the role's **Assignments** tab to see who holds it.
2. Give each of those users and groups another role, from the Users page or the Groups page.
3. Go back to the Roles page. Once **ASSIGNED TO** shows 0 users and 0 groups, the **Delete role** icon becomes available.
### **Set a default role for single sign-on**
Users who sign in through single sign-on for the first time receive a default role. Choose it under **Default User Role** in **Settings → Workspace → Security → SSO Configuration**. The dropdown lists custom roles alongside the built-in ones. See [OIDC](https://help.tellius.com/settings/security/sso-configuration/oidc) and [SAML](https://help.tellius.com/settings/security/sso-configuration/saml).
### **Example roles**
| Role idea | How to set it up |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Kaiya only** | Turn on the Kaiya modules and leave the Analytics modules at **No Access**. The editor raises the data modules that Kaiya needs. |
| **Analytics without Kaiya** | Turn on the Analytics modules you need, such as **Vizpad**, and leave the Kaiya modules at **No Access**. This suits teams not yet moving to Kaiya. |
| **Kaiya builder** | Give **Full Access** to **Missions** and **Apps**, so the user can create, edit and publish them. The editor raises **Chat** to **Full Access**. |
| **Kaiya viewer** | Give **Read Access** to **Missions** and **Apps**, so the user can open what builders publish without changing it. |
| **Context model builder** | Give **Full Access** to **Context Models**, **Chat** and **Datasets**, so the user can build context models in the chat and keep them up to date. |
| **Context model user** | Give **Read Access** to **Context Models** and **Chat**, so the user can ask questions on context models that others maintain. |
### **Best practices**
* **Start from nothing.** A new role starts at **No Access** everywhere. Turn on only what the role needs, and let the editor raise the modules they depend on.
* **Check the default group's role.** It reaches every new user, so make sure it gives only what everyone should have.
* **Use groups for shared access.** Give a group the role its members share. Each member then gets the highest level across their own role and their groups' roles.
* **Check before you change.** Open **View effective access** to see which role gives each module. If a user has more access than expected, it shows you which role or group to change.
* **Name and describe roles clearly.** A clear name and a one-line description help others pick the right role when they assign it.
### **Related pages**
* [User roles and permissions](https://help.tellius.com/settings/users-and-access/user-roles-and-permissions)
* [Users](https://help.tellius.com/settings/users-and-access/users)
* [Groups](https://help.tellius.com/settings/users-and-access/groups)
* [My Profile](https://help.tellius.com/settings/my-profile-1)
* [OIDC](https://help.tellius.com/settings/security/sso-configuration/oidc)
* [SAML](https://help.tellius.com/settings/security/sso-configuration/saml)
---
# 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://help.tellius.com/tellius-6.4/settings/users-and-access/custom-roles.md?ask=&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.
