> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contextual.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Role-Based Access Control (RBAC)
> Define custom roles and permission bundles across agents, datastores, and more.
*********Contextual AI is excited to introduce Role-Based Access Control (RBAC). RBAC is exclusive to customers on our Provisioned Throughput plan. Please contact your account team for more information.*********
Admins can now define custom roles with tailored permission bundles across key objects — including Agents, Datastores, Billing, and other administrative features. Permissions can be scoped to specific Agents or Datastores, enabling finer-grained governance so every team member has the right level of access for their role.
**Groups** make access management even simpler: add multiple users to a Group, then assign that Group to a Role.
## Roles
### Navigating to the Roles Page
First, click `Settings` under `Admin` in the side-panel.
Next, click `Roles` under `Access Control`.
### Default Roles
Your tenant comes with three default roles:
* `Admin`: Default role with full access to agents, datastores, and workspace settings.
* `User`: Default role that every new user is automatically assigned to. This role **does not** come with any access to agents or datastores.
* `Power User`: Default role that grants read access to all agents and datastores.
By default, all new users are given the `User` role. They won't be able to access agents or datastores until they’re assigned a Role with higher-level permissions.
### Creating a Custom Role
You can create custom roles to meet your governance needs. Here are examples of custom roles you can create:
* **Billing Admin** – Access to billing and usage features
* **Data Ingestor** – Manage and ingest documents within specific Datastores
* **Agent User** – Query and interact with designated Agents
* **Agent Admin** – Maintain and optimize designated Agents
First, click "New Role" in the **Roles** page.
Second, input a Role Name and Description. Click "Create role".
### Configuring Role Permissions
After creating a Role, you will be automatically directed to the Role page. The first tab is for you to configure permissions. Click “Add Permission” to associate a permission with the Role.
You will need to select what type of object you want to grant access to. You have three options:
* `Agents`: Select this to give permissions on an agent
* `Datastores`: Select this to give permissions on a Datastore
* `Admin Tools`: Select this to give access to admin functions like billing and [annotating feedback](/how-to-guides/feedback).
You can then configure permissions relevant to the object type you selected.
#### Configuring Agent Permissions
On the left, you’ll see a **list of available permissions**. Each defines what actions the Role can take.
* `Query Agents`: This permission will let assigned users query the agent.
* `Manage Agents`: This permission will let assigned users query the agent and edit its configs. It is a superset of `Query Agents`.
* `Create Agents`: This permission will let assigned users create an agent.
On the **right**, you’ll see the **objects** these permissions apply to.
* For `Query Agents` and `Manage Agents`, you can select specific agents or select `All Agents`.
* The`Create Agents` permission will apply globally.
**Important:** To query data from an agent’s linked datastores, a user must have both (i) `Query Agents` or `Manage Agents` and (ii) `Read Documents` (or higher) on the specific datastores. This ensures that when an agent is linked to multiple datastores, users can only query the ones they are permitted to access.
Example:
* `Agent_1` is linked to `Datastore_1` and `Datastore_2`.
* The user has `Query Agents` on `Agent_1` and `Read Documents` on `Datastore_1` only.
* As a result, only documents from `Datastore_1` will be retrieved.
#### Configuring Datastore Permissions
On the left, you’ll see a **list of available permissions**. Each defines what actions the Role can take.
* `Read Documents`: This permission will let assigned users see the datastore and read documents inside.
* `Manage Documents`: This permission will let assigned users read documents, as well as upload/delete them. It is a superset of `Read Documents`.
* `Manage Datastores`: This permission will let assigned users manage documents, as well as edit the datastore configs. It is a superset of `Manage Documents`.
* `Create Datastores`: This permission will let assigned users create a datastore.
On the **right**, you’ll see the **objects** these permissions apply to.
* For `Read Documents` , `Manage Documents` and `Manage Datastores`, you can select specific datastores or select `All Datastores`.
* The`Create Datastores` permission will apply globally.
**Important:** To query data from an agent’s linked datastores, a user must have both (i) `Query Agents` or `Manage Agents` and (ii) `Read Documents` (or higher) on the specific datastores. This ensures that when an agent is linked to multiple datastores, users can only query the ones they are permitted to access.
#### Configuring Admin Permissions
On the left, you’ll see a **list of available permissions**. Each defines what actions the Role can take.
* `Create Agents`: This permission will let assigned users create an agent.
* `Create Datastores`: This permission will let assigned users create a datastore.
* `Manage Billing & Usage`: This permission will let assigned users view and configure the `Billing` page.
* `Manage Feedback Annotation`: This permission will let assigned users [view and annotate agent-level feedback](/how-to-guides/feedback).
All these permissions apply globally.
### Review your Permissions
Review all the permissions that you have provisioned for the Role. You can add more permissions or remove existing ones by clicking on the three dots beside each permission and clicking "Remove".
### Assigning a User to a Role
To assign a user to the Role, click the `Assigned Users` tab in the Roles Page.
Next, click "Assign Users". You'll be able to select multiple users to add to the role. Click "Confirm".
Third, review the users you've added. You can add more users or remove existing ones by clicking on the three dots beside a user and clicking "Remove".
**You’re all set!** The assigned users now have the access defined in this Role.
### Dealing with Role Conflicts
If a user is assigned to two roles with different permissions on the same object, we will take the **union of permissions**. Example:
* User is assigned to `Role A` which is given `Query Agents` on `All Agents`
* User is also assigned to `Role B` which is given the higher-level `Manage Agents` on `Agent A`.
* Outcome:
* User will have `Manage Agents` on `Agent A`
* User will have `Query Agents` on every other agent.
### Managing Roles
After creating a Role, you can return to its configuration page at any time. To do so, navigate to the **Roles** page and click on the Role you want to edit.
You can also delete a Role by clicking on the three dots beside it and clicking "Delete".
### Creating Agents and Datastores
If a user has created an Agent or Datastore, an owner Role will automatically be created with `Manage Agent` or `Manage Datastore` permissions. The user will automatically be assigned to that Role.
## Groups
### Navigating to the Groups page
Groups can help simplify access management. You can add multiple users to a Group and assign the Group to a Role.
First, click `Settings` under `Admin` in the side-panel.
Next, click "Groups" under "Access Control".
### Creating a Group
Click "New Group".
Fill in Group Name and Description
Click "Create group". You'll be automatically redirected to the Group page.
### Assigning Users to the Group
Click the tab "Assigned Users".
Click "Assign Users" and select the users you want to include in the Group. Click "Confirm".
Review the users you have added. You can add more users to the Group or remove existing users by clicking the three dots and clicking "Remove".
### Associating a Group with a Role
Navigate to the first tab: "Roles".
Click "Add Roles".
You can select roles to associate with your Group.
Click "Add Roles". You can add more roles or remove existing ones by clicking on the three dots and clicking "Remove".
**You're set!** Members of the Group now have have the access defined in the attached Roles.
### Managing a Group
After creating a Group, you can return to its configuration page at any time. To do so, navigate to the **Groups** page and click on the Group you want to edit.
You can also delete a Group by clicking on the three dots beside it and clicking "Delete".
## User Management
You can view the roles and groups associated with each user.
First, navigate to `Members` in the `Access Control` tab. You will see the list of members in your workspace.
To see the **roles** assigned to the user, click the `Expand` button in the `Roles` column. You will see (i) the assigned roles, (ii) the permissions included in each role, and (iii) whether it was assigned directly to the user or inherited via group membership. You can also open up the Role Page with the top-left button.
To see the **groups** that the user belongs to, click the `Expand` button in the `Groups` column. You will see (i) the user's groups and (ii) the roles associated with each group. You can also open up the Group Page with the top-left button.
