Skip to main content
A role is a named set of permissions. Everyone in an organization holds exactly one role, and the role decides what they can do there. Your organization starts with four built-in roles. Admins can change what each one holds, create roles of their own, and give a single member exceptions. This page is the reference for all of it.

Built-in roles

Two more kinds of people appear in the member list:
  • Custom roles your organization defines. Each one starts from Admin, Billing admin, or Member. See Create a custom role.
  • Guests, people outside the organization who were invited into one of its workspaces. See Guests.

Permissions reference

These are the permissions you see in Settings → Organization, grouped as the editor groups them. The columns show what each built-in role holds before anyone changes it. ✓ means the role holds it by default. — means it doesn’t.

Integrations

Workspaces

Scripts and sandbox

Usage and billing

See Billing, credits, and plans for usage caps and credit requests.

People and organization

Integration calls and Agent models

Two more settings sit in the same editor, under Integrations. They aren’t checkboxes.
  • Integration calls limit which integration requests a member or a role may make, in the app and in everything they run. Holders of Manage integration permissions set them. See Integration calls.
  • Agent models limit which models a member’s sessions, Agents, and subagents may run. Holders of Manage members set them. Model calls that scripts make follow Integration calls instead. See Models.

What turning a permission off does

Most permissions simply hide or refuse an action. A few have effects you should know about:

The rules behind every change

One rule decides who can change what: you can only hand out what you hold, and you can only manage people who hold nothing you lack.
  • You can grant only permissions you hold. An Admin without Manage billing can’t give it to anyone.
  • You can manage only members no stronger than you. An Admin can change or remove another Admin who holds the same permissions. An Admin can’t manage a Billing admin, because a Billing admin holds Manage billing. Nobody but the Owner can act on the Owner.
  • You can give only roles whose permissions you hold. With the built-in roles, the Owner can give any role, an Admin can give Admin and Member, and a Billing admin or Member can give none.
  • Nobody changes their own permissions. You can open your own to see what you hold. The one exception: a holder of Manage integration permissions can change their own Integration calls.
  • Ownership is never handed out in pieces. Delete the organization and Transfer ownership belong to the Owner alone. Ownership moves only by transferring it.
  • The Member role never holds Manage integration permissions. Neither does any role built on Member. Start a role from Admin or Billing admin to grant it.

Requirements

Two entries in the editor bind a member instead of empowering them:
  • Must use two-factor authentication. The member signs in with an authenticator app. Until they set one up, they’re asked to before they can continue, whichever account they have open. See Two-factor authentication.
  • Hide the Scripts tab. The member’s sidebar lists sessions only. They keep their scripts and the ones shared with them, and the agent still uses them.
No role has a requirement by default. Anyone with Manage members can set one on a role or on a member they can manage. Requirements never apply to the Owner.

Change what a role holds

Changing a role changes it for everyone who holds it, right away.
1

Open the roles

Go to Settings → Organization and select Roles. You need Manage members.
2

Pick a role

The list shows the built-in roles and your organization’s own, with how many people hold each. You see only roles you can give.
3

Change its permissions

Check or clear permissions. A badge marks each one that differs from the role’s standard set: Added, Removed, or Required. A lock means you can’t change that entry; hover it to see why.
4

Save

Select Save role. Everyone with the role gets the change at once. Exceptions set on individual members stay theirs.
A dot next to a built-in role means your organization changed it from the standard set. To undo your changes, select Use the role standard set.

Create a custom role

1

Start a new role

In Settings → Organization → Roles, select New role.
2

Name it and pick a starting point

Enter a name, then choose what it starts from under Start from: Member, Admin, or Billing admin. It starts with what that role holds in your organization today.
3

Create it, then set its permissions

Select Create role. Change its permissions, then select Save role.
4

Give it to people

Choose it in the role picker of the member list, in an invitation, or in a single sign-on role rule.
You can rename a custom role at any time. You can delete it only once nobody holds it, no pending invitation offers it, and no single sign-on rule gives it.

Give one member an exception

Sometimes one person needs more or less than their role.
  1. In Settings → Organization, find the member in the member list.
  2. Select the permissions button next to their name.
  3. Check or clear permissions, or change their Integration calls or Agent models.
  4. Select Save permissions.
The member’s row now shows Custom. Their exceptions stay when their role is edited, and follow them until their role changes or they leave. Changing their role clears their exceptions, except requirements such as two-factor authentication. To clear them yourself, select Reset to the role role.

Assign roles

  • When you invite someone, pick their role in the invitation. See Invite members.
  • For an existing member, change the role in the member list. You can select several members to change them together.
  • From your identity provider, let single sign-on role rules set roles from groups.
In every case you can give only a role whose permissions you hold.

Guests

A guest is someone outside your organization who was invited into one of its workspaces. Guests appear in the member list as Guest, with the workspaces they were let into.
  • Guests hold no organization permissions.
  • Their work runs on their own account and their own credits, so you can’t set a usage cap for them.
  • They reach the workspace they were invited to, and the connections shared into it.
Inviting a guest needs Invite people outside the organization, which only Owners and Admins hold by default. Inviting someone who is already a member, or whose email is on one of your verified domains, doesn’t count as inviting a guest. To take a guest’s access away, remove them from the workspace.