> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Roles and Permissions
> Create workspace roles that decide which agents each teammate can use and what they can do with them.
A role decides which agents a teammate can use and what they can do with them. Every workspace ships with three built-in roles, **Owner**, **Admin** and **Member**, and owners and admins can add their own.
Workspace settings \→\ Access \→\ Roles
> [!NOTE]
>
> Roles only ever restrict. Your workspace keeps working as it does today until you change one.
## What roles are
### The two things a role controls
| Part | What it decides |
| - | - |
| **Agent access** | Which agents the role can see and open: **All agents** or **Selected agents** |
| **Capabilities** | What the role can do with those agents, and with the workspace |
Capabilities apply the same way to every agent the role reaches, so people who need different agents need different roles.
### The built-in roles
| Role | What it is |
| - | - |
| **Owner** | Everything, plus deleting the workspace, changing the payment method and transferring ownership |
| **Admin** | Full access to agents and workspace settings, and manages people and roles |
| **Member** | The default for new teammates. Edit it to change what an ordinary teammate can do |
**Owner** and **Admin** are locked and pick up new capabilities on their own. None of the three can be deleted.
### Where roles live
Roles sit under **Workspace settings**, on the **Access** tab. **People** lists everyone and the role each holds, and **Roles** lists the roles and what each grants.
> [!WARNING]
>
> Only owners and admins see the **Roles** sub-tab and can change anyone's role.
### When to create your own
Create a role when not everyone should change everything, such as a business-critical agent most of the team should run but not edit. If everyone should do everything, the built-in roles are enough.
## How to use roles
### Create a role
**1. Open Create role**
Go to **Workspace settings**, open the **Access** tab, select **Roles**, then select **Create role**.
**2. Name the role**
Fill in **Role name** and a **Description**. Admins see the description when they assign the role.
Workspace settings \→\ Access \→\ Roles \→\ Create role
**3. Choose the agents the role can reach**
In the **Agent access** card, pick **All agents** or **Selected agents**. For **Selected agents**, tick the agents the role should reach under **Allowed agents**.
Workspace settings \→\ Access \→\ Roles \→\ Create role \→\ Agent access
> [!NOTE]
>
> An agent created after you save the role is kept out of it. Add new agents to a role's **Allowed agents** list yourself.
**4. Choose what the role can do**
In the **Capabilities** card, expand a group and tick what the role needs, or use **Select all**. Ticking **Create & edit** also ticks **Run**.
Workspace settings \→\ Access \→\ Roles \→\ Create role \→\ Capabilities
**5. Select Save role**
The role appears in the Roles table and can be assigned straight away.
> [!NOTE]
>
> Managing people and roles, and the owner-only actions, cannot be given to a role you create.
### Invite someone with a role
**1. Open Invite members**
Go to **Workspace settings**, open the **Access** tab, stay on **People**, and select **Invite members**.
**2. Add the people and pick the role**
Type each address under **Enter email** and select its suggestion. Open **Role** and choose one. It applies to the whole batch and defaults to **Member**.
Workspace settings \→\ Access \→\ People \→\ Invite members
**3. Select Send invite**
Each person appears in the People list with a **Pending invitation** badge until they accept.
### Change someone's role
On the **People** sub-tab, select the role on a person's row and choose a new one. The change takes effect immediately.
Workspace settings \→\ Access \→\ People
You can only move someone to a role below your own, and you cannot change your own role. Making someone the owner goes through transferring ownership, which only the current owner can start.
### Give one agent to specific roles
Open an agent and select **Manage access** in the header.
Any agent \→\ Manage access
Choose **Selected roles**, adjust **Allowed roles**, and select **Save changes**. It edits the same setting as a role's **Allowed agents** list.
> [!NOTE]
>
> **Allowed roles** starts with every role that already reaches the agent, including roles set to **All agents**. Remove the ones that should not have it.
### Delete a role
Open the actions menu at the end of a role's row in the Roles table and choose **Delete**. Only roles you created can be deleted, and only once nobody holds them. Select the **Members** count to see who still does.
## Troubleshooting
> **I cannot see the Roles sub-tab**
>
> Only owners and admins manage roles. Ask one to make the change.
> **Save role does nothing and an error appears**
>
> A role must grant at least one capability, and a role set to **Selected agents** needs at least one agent ticked. Add what is missing and select **Save role** again.
> **A teammate cannot find an agent they used yesterday**
>
> Their role no longer reaches that agent, so it is hidden from their lists. Add the agent to the role's **Allowed agents**, or add their role under **Manage access** on the agent.
## Next steps
> **[Workspace Setup](https://docs.beam.ai/01-getting-started/workspace-setup/workspace-setup.md)**
>
> Create or join a workspace and invite your first teammates.
> **[Azure SSO Setup](https://docs.beam.ai/05-resources/team-management-sso/team-management-sso.md)**
>
> Let your team sign in with your organization's existing credentials.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.