> ## 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 answers two questions about a teammate: which agents they can use, and what they can do with those agents. Every workspace ships with three built-in roles, **Owner**, **Admin**, and **Member**, and owners and admins can add roles of their own on top of them.
Roles only ever restrict. A workspace keeps working exactly as it did until you change one, so there is nothing to set up before you need it.
What roles are
The two things a role controls
Every role is made of the same two parts, and the role editor shows them in this order.
| Part | The question it answers | Where it lives in the editor |
| - | - | - |
| **Agent access** | Which agents can people with this role see and open? | The **Agent access** card at the top |
| **Capabilities** | What can they do with those agents, and with the workspace? | The **Capabilities** card below it |
Agent access is either **All agents** or a hand-picked list under **Selected agents**. Capabilities are checkboxes in collapsible groups, and whatever you tick applies the same way to every agent the role can reach. There is no per-agent level.
Both parts belong to the role, not to a person. Two people who need different sets of agents need two different roles.
The built-in roles
| Role | What it is |
| - | - |
| **Owner** | Full access to everything, plus the actions no other role can be given: deleting the workspace, changing the payment method, and transferring ownership. |
| **Admin** | Full access to agents and workspace settings, and can manage people and roles. |
| **Member** | The default for new teammates. This is the role you edit when you want to change what an ordinary teammate can do. |
**Owner** and **Admin** are locked. They carry a **Locked** badge in the Roles table, their capabilities open read-only, and they cannot be deleted. As new features are added to Beam, those two roles pick up the new capabilities on their own. **Member** is editable, but like the other built-in roles it cannot be deleted.
Where roles live
Roles sit under **Workspace settings**, on the **Access** tab. The tab has two sub-tabs:
* **People** lists everyone in the workspace and the role each person holds.
* **Roles** lists the roles themselves and what each one grants.
Only owners and admins see the **Roles** sub-tab and can change anyone's role. Everyone else sees **People** as a read-only list. If you cannot find **Roles**, that is why.
When to create your own
Reach for a custom role when more than a couple of people share a workspace and not all of them should be able to change everything in it.
* A live agent runs a business-critical process and you want most of the team to run it, not edit it.
* A new teammate should start with a narrow set of agents rather than all of them.
* Finance owns billing, IT owns SSO, and neither needs to touch agents.
* An outside collaborator needs one agent and nothing else.
If everyone in your workspace is meant to do everything, the built-in roles are already enough and you do not need to create any.
How to use roles
Create a role
Go to **Workspace settings**, open the **Access** tab, then select **Roles**.
The **Create role** button sits in the page header, to the right of the heading. The role editor opens.
Fill in **Role name**, which is required. Add a **Description** as well.
The description is shown to admins when they assign the role. A line like "runs the invoicing agents, cannot edit them" saves someone guessing later.
In the **Agent access** card, open the dropdown on the right and pick one:
* **All agents**: every agent in the workspace is available to the role.
* **Selected agents**: only the agents you pick.
Choosing **Selected agents** enables the **Allowed agents** list below it. Search it, tick the agents this role should reach, and leave the rest unticked.
An agent created after you save the role is kept out of it. New agents stay private until someone adds them to a role's **Allowed agents** list, so widening a role is always a deliberate edit rather than something that happens on its own.
In the **Capabilities** card, expand a group and tick the boxes the role should have. Use **Select all** at the top of a group to tick the whole group at once.
The groups are:
| Group | What it covers |
| - | - |
| **Agents** | **Create & edit**, **Run**, and **Delete**, applied to the agents in the role's set. |
| **Beam AI** | **Projects**, **Skills**, and **Views**, each with its own nested **Delete**. |
| **Integrations** | Connecting integrations, managing other people's connections, and building custom integrations. |
| **Workspace Settings** | General settings, notifications, billing, and SSO. |
| **API Keys** | Creating and revoking API keys. |
| **Inbox** | Reading and clearing workspace notifications. |
Some capabilities depend on others, and Beam keeps them consistent for you. **Create & edit** covers running an agent, because you cannot build one without testing it, so ticking it ticks **Run**. Deleting is always its own checkbox and never comes along with anything else. Untick a capability that others depend on and those are unticked too.
The role appears in the Roles table straight away and can be assigned from that point on.
A role has to grant at least one capability, and a role set to **Selected agents** has to have at least one agent ticked. If either is missing, **Save role** refuses and tells you what to add.
Two things never appear in the Capabilities list. Managing people and roles is limited to owners and admins and cannot be handed to a role you create. Deleting the workspace, changing the payment method, and transferring ownership belong to the owner alone. Both sets are visible, greyed out, when you open a locked role, so you can see what Owner and Admin hold.
The Roles table summarises agent access in its **Agent access** column: **All agents** for an unrestricted role, a row of agent icons for a narrowed one, with a count such as **+1** when there are more than three, and **No access** for a role that has been cut off from every agent.
Invite someone with a role
Every invitation carries a role. Inviting is also covered in [Workspace Setup](/01-getting-started/workspace-setup/workspace-setup#inviting-team-members); this section adds the role step.
Go to **Workspace settings**, open the **Access** tab, and stay on **People**.
The button is in the page header. The **Invite members** dialog opens.
Type an address under **Enter email**, then select it from the suggestion that appears beneath the field to add it. Repeat for each person. Everyone in the batch receives the same role.
Open **Role** and choose the role these people should hold.
**Member** is filled in for you unless you change it. If you send the invite without touching this field, everyone in it arrives as a Member.
Each person gets an invitation email and appears in the People list with a **Pending invitation** badge until they accept.
Change someone's role
On the **People** sub-tab, each row shows the person's current role on the right. Select it to open the list of roles you can move them to, and choose one. The change takes effect immediately.
You cannot change your own role, so no control appears on your own row. That prevents an admin from demoting themselves out of the workspace they administer. Ask another owner or admin if your own role needs to change.
You can only move someone to a role below your own. Making someone an owner is separate: it goes through transferring ownership, and only the current owner can start it.
Give one agent to specific roles
You do not have to work from the role side. Open an agent and select **Manage access** in the header to decide which roles reach that one agent.
The dialog mirrors the role editor from the other direction. **All roles** makes the agent available to everyone, **Selected roles** limits it to the roles you tick under **Allowed roles**, and **Save changes** applies it. Whichever side you edit from, you are changing the same thing, so an agent removed here also disappears from that role's **Allowed agents** list.
Switching to **Selected roles** does not hand you an empty list. **Allowed roles** fills in with every role that already reaches this agent, including roles you never pointed at it by name, because a role set to **All agents** reaches it too. Read the list as "who can get to this agent today", then remove the ones who should not.
**Owner** never appears in the list. Owners reach every agent and that cannot be taken away. **Manage access** is only available to owners and admins.
Delete a role
Open the role actions menu at the end of a role's row in the Roles table and choose **Delete**. Only roles you created can be deleted: the **Member** row offers **Edit** alone, and the locked **Owner** and **Admin** rows have no menu at all.
A role cannot be deleted while people still hold it. Move everyone to another role first. The **Members** count in the Roles table tells you how many there are, and selecting that number opens the People list filtered to that role.
Troubleshooting
**Cause**: Roles are managed by owners and admins only.
**Solution**:
* Check the role on your own row under **Workspace settings** → **Access** → **People**.
* Ask an owner or admin to make the change, or to move you to **Admin**.
**Cause**: The role is missing something it needs.
**Solution**:
* A role must grant at least one capability. Tick something under **Capabilities**.
* A role set to **Selected agents** must have at least one agent ticked under **Allowed agents**.
* If the agent list is still loading, wait a moment and select **Save role** again.
**Cause**: People are still assigned to it.
**Solution**:
* Select the number in the **Members** column to open the People list filtered to that role.
* Move each person to another role, then delete it.
**Cause**: Their role no longer reaches that agent. An agent outside a role's set is hidden rather than shown as blocked, so it disappears from their lists.
**Solution**:
* Open the role and check **Agent access**. If it is set to **Selected agents**, add the agent to **Allowed agents**.
* Or open the agent, select **Manage access**, and add their role under **Allowed roles**.
**Cause**: The person's role does not grant that capability. Restricted controls stay visible and explain themselves rather than disappearing.
**Solution**:
* Publishing a workflow needs the **Create & edit** capability under **Agents**.
* Running one needs **Run**.
* Add the capability to their role, or move them to a role that has it.
**Cause**: This is deliberate. The role control does not render on your own row, so nobody can remove their own access by accident.
**Solution**:
* Ask another owner or admin to change it for you.
* Becoming the owner is a separate flow. The current owner starts a transfer of ownership, and you accept it from the People list.
Next steps
Create or join a workspace and invite your first teammates.
Let your team sign in with your organization's existing credentials.
Build the shared data views a role can be given access to.
Browse the reusable capabilities available in your workspace.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.