# Roles and permissions

> Source: https://elaichi.ai/docs/guides/members/roles/

A **role** is a named bundle of permissions. Each person holds exactly **one** role — changing someone's access means replacing their role, not adding a second one.

**Where to find it:** **Settings → People → Roles**

You need the **Manage roles** permission (`role:manage`) to create or edit custom roles. Built-in roles are always visible; only custom roles can be changed.

## Built-in roles

Every organization starts with eight system roles. They can't be edited or deleted. Elaichi keeps their permissions in sync when the product adds new capabilities.

Six of them form a ladder — each rung can do everything the rung below it can, plus one more job:

**Guest → Member → Team Admin → People Admin → Org Admin → Org Owner**

| Role | Who it's for | What it can do |
| --- | --- | --- |
| **Org Owner** | The people ultimately responsible for the workspace | Everything in the permission catalog, including billing. At least one member must always hold this role. |
| **Org Admin** | Day-to-day administrators | Everything except managing billing and the subscription, and deleting the organization. |
| **People Admin** | Whoever runs joiners and leavers | Everything Team Admin can do, plus inviting, removing, and assigning roles to members. |
| **Team Admin** | Leads who run teams | Everything Member can do, plus managing any team and its membership, even teams they didn't create. |
| **Member** | Default for new people (invites, domain join, and SCIM when no group is mapped) | Browse connectors, connect and share accounts, build and share templates and toolboxes, create teams (and run the ones they create), publish automations that make changes, publish dashboard links while your organization allows them, reach your organization's MCP endpoint, run tools, and create their own API tokens. |
| **Guest** | Read-only guests | Browse the connector catalog. Cannot connect accounts, run tools, or change anything. |

Two more roles sit **outside** the ladder, for people who need one narrow slice of access. Both are free seats:

| Role | Who it's for | What it can do |
| --- | --- | --- |
| **Billing Admin** | Finance | Manage billing and the subscription — and nothing else. No workspace or product access. |
| **Auditor** | Compliance and oversight | Read-only visibility across the organization, including the audit log. Cannot change anything and cannot run tools. |

:::callout{type="info"}
Seeing the organization, the member directory, teams, and role names follows from simply being a member — there is no permission to toggle for those. Even a **Guest** can see who is in the organization.
:::

### Permissions by built-in role

The six ladder roles:

| Permission | Owner | Org Admin | People Admin | Team Admin | Member | Guest |
| --- | :---: | :---: | :---: | :---: | :---: | :---: |
| `org:manage` | ✓ | ✓ | | | | |
| `org:delete` | ✓ | | | | | |
| `billing:view` | ✓ | ✓ | | | | |
| `billing:manage` | ✓ | | | | | |
| `team:create` | ✓ | ✓ | ✓ | ✓ | ✓ | |
| `team:manage` | ✓ | ✓ | ✓ | ✓ | | |
| `member:manage` | ✓ | ✓ | ✓ | | | |
| `role:manage` | ✓ | ✓ | | | | |
| `connector:view` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `connector:create` | ✓ | ✓ | | | | |
| `connector:share` | ✓ | ✓ | | | | |
| `connector:manage` | ✓ | ✓ | | | | |
| `connection:create` | ✓ | ✓ | ✓ | ✓ | ✓ | |
| `connection:share` | ✓ | ✓ | ✓ | ✓ | ✓ | |
| `connection:manage` | ✓ | ✓ | | | | |
| `template:create` | ✓ | ✓ | ✓ | ✓ | ✓ | |
| `template:share` | ✓ | ✓ | ✓ | ✓ | ✓ | |
| `template:manage` | ✓ | ✓ | | | | |
| `toolbox:create` | ✓ | ✓ | ✓ | ✓ | ✓ | |
| `toolbox:share` | ✓ | ✓ | ✓ | ✓ | ✓ | |
| `toolbox:view` | ✓ | ✓ | | | | |
| `toolbox:manage` | ✓ | ✓ | | | | |
| `restriction:view` | ✓ | ✓ | | | | |
| `restriction:manage` | ✓ | ✓ | | | | |
| `restriction:override` | ✓ | ✓ | | | | |
| `audit:view` | ✓ | ✓ | | | | |
| `api_token:view` | ✓ | ✓ | | | | |
| `api_token:create` | ✓ | ✓ | ✓ | ✓ | ✓ | |
| `api_token:manage` | ✓ | ✓ | | | | |
| `sso:view` | ✓ | ✓ | | | | |
| `sso:manage` | ✓ | ✓ | | | | |
| `logging:view` | ✓ | ✓ | | | | |
| `logging:manage` | ✓ | ✓ | | | | |
| `notification:view` | ✓ | ✓ | | | | |
| `notification:manage` | ✓ | ✓ | | | | |
| `tool:execute` | ✓ | ✓ | ✓ | ✓ | ✓ | |
| `assistant:manage` | ✓ | ✓ | | | | |
| `automation:publish` | ✓ | ✓ | ✓ | ✓ | ✓ | |
| `dashboard:publish` | ✓ | ✓ | ✓ | ✓ | ✓ | |

The two free-seat roles, which only hold what their job needs:

| Permission | Billing Admin | Auditor |
| --- | :---: | :---: |
| `billing:view` | ✓ | ✓ |
| `billing:manage` | ✓ | |
| `connector:view` | | ✓ |
| `toolbox:view` | | ✓ |
| `restriction:view` | | ✓ |
| `api_token:view` | | ✓ |
| `sso:view` | | ✓ |
| `logging:view` | | ✓ |
| `notification:view` | | ✓ |
| `audit:view` | | ✓ |

## Permission catalog

These are the permissions you can tick when creating a custom role. The role editor groups them the same way.

Four verbs repeat across the catalog, and they always mean the same thing:

- **create** — make your own, and manage what you made.
- **share** — decide who else can use the thing you made.
- **view** — see organization-wide settings of that kind. On connections, templates, and toolboxes it does **not** hand you other people's resources.
- **manage** — administer organization-wide settings of that kind. On connections, templates, and toolboxes it reaches only what you own or hold an `edit` share on.

:::callout{type="info"}
Connections, templates, and toolboxes work on grants, not on org-wide permissions. A bare `:view` or `:manage` never reaches a resource nobody shared with you — not for an Org Admin, not for an Org Owner.
:::

### Organization

| Permission | What it allows |
| --- | --- |
| `org:manage` | Edit the organization name, short URL name, logo, and verified domains. |
| `org:delete` | Permanently delete the organization and everything in it. Held only by **Org Owner**. |
| `team:create` | Create a team. You become its team admin, with full control of that team: rename it, add and remove people, appoint and step down admins, and delete it. Anyone can leave a team. |
| `team:manage` | Create, edit, and delete any team, including ones you are not on, and manage who belongs to it and who administers it. Can also remove a team's last admin. |
| `member:manage` | Invite people, change roles, and remove members. |
| `role:manage` | Create custom roles and choose which permissions they include. |

### Billing

| Permission | What it allows |
| --- | --- |
| `billing:view` | View plan, subscription, and billable-seat details. |
| `billing:manage` | Start checkout and manage the organization subscription. |

### Connectors

| Permission | What it allows |
| --- | --- |
| `connector:view` | View the connector catalog. |
| `connector:create` | Author custom connectors for the organization. |
| `connector:share` | Share custom connectors with teams or everyone at your organization. |
| `connector:manage` | Edit or delete other members' custom connectors, and set the organization's own OAuth application for a connector. |

### Connections

| Permission | What it allows |
| --- | --- |
| `connection:create` | Connect accounts for personal (user-scoped) use. |
| `connection:share` | Connect accounts shared with a team or everyone at your organization. |
| `connection:manage` | Reconnect, edit, or delete a connection you own or hold an `edit` share on. Does not reach a connection nobody granted you. |

:::callout{type="info"}
No organization permission reaches a connection nobody granted you — not even `connection:manage`, not even an Org Owner. Access to a connection always comes from owning it or holding a share on it, directly or through a team.
:::

### Templates

| Permission | What it allows |
| --- | --- |
| `template:create` | Create tool templates and add tools to them. |
| `template:share` | Share templates with members, teams, or everyone at your organization. |
| `template:manage` | Edit or delete a template you own or hold an `edit` share on. |

### Toolboxes

| Permission | What it allows |
| --- | --- |
| `toolbox:create` | Create toolboxes and add tools to them. |
| `toolbox:share` | Share toolboxes with members, teams, or everyone at your organization. |
| `toolbox:view` | View organization-wide synthetic tool definitions. Not toolbox visibility, despite the name. |
| `toolbox:manage` | Edit or delete a toolbox you own or hold an `edit` share on. |

### Automations

| Permission | What it allows |
| --- | --- |
| `automation:publish` | Publish any version of an automation you own or hold an `edit` share on, including ones that make changes, delete things, or start from a webhook or a Slack message. A step that deletes still needs an approval step before it. `automation:manage` is only needed to reach automations beyond those. |

### Dashboards

| Permission | What it allows |
| --- | --- |
| `dashboard:publish` | Create public links for dashboards you can edit. Links only work while an admin has turned on public links in your organization's settings. |

### Governance

| Permission | What it allows |
| --- | --- |
| `restriction:view` | View organization access restrictions. |
| `restriction:manage` | Limit which connectors and tools roles or members can use. |
| `restriction:override` | Create user-level restriction exceptions that replace role-level rules for that member. |
| `audit:view` | See every event across the organization; without it you see your own activity and activity on resources you own or can edit. |

### Tool execution

| Permission | What it allows |
| --- | --- |
| `tool:execute` | Run connected-account and synthetic tools. |

### Assistant

| Permission | What it allows |
| --- | --- |
| `assistant:manage` | Configure provider keys, models, and assistant settings. |

The in-app agent is not yet available to customer organizations, so this permission has no effect today. To drive Elaichi with AI, point your own AI client at the MCP endpoint — see [How Elaichi connects to AI clients](/guides/mcp-servers/how-it-works).

### API tokens

| Permission | What it allows |
| --- | --- |
| `api_token:view` | View organization API token metadata. |
| `api_token:create` | Create, list, and revoke your own organization API tokens. |
| `api_token:manage` | Revoke other members' organization API tokens. |

### SSO & identity

| Permission | What it allows |
| --- | --- |
| `sso:view` | View SSO, SCIM, and group-mapping configuration. |
| `sso:manage` | Configure SAML/OIDC SSO, SCIM tokens, and group-to-role mappings. |

### Logging

| Permission | What it allows |
| --- | --- |
| `logging:view` | View organization logging destinations. |
| `logging:manage` | Forward organization events to your logging tools. |

### Notifications

| Permission | What it allows |
| --- | --- |
| `notification:view` | View organization notification destinations. |
| `notification:manage` | Send organization events to Slack or email. |

## Create a custom role

1. Open **Settings → People → Roles**.
2. Choose **Create** (or edit an existing custom role).
3. Name it after the job, such as "Support lead" or "Read-only analyst".
4. Tick the permissions from the catalog above.
5. Save. Assign the role to people from **People**, or map it from SCIM groups under **Settings → SSO**.

**You'll know it worked when:** People with that role see the screens and actions you intended, and nothing more.

:::callout{type="info"}
You can only grant permissions you hold yourself. If a permission is greyed out while you build a role, it is one your own role does not carry.
:::

## How roles combine with other access

Roles are only one layer:

```mermaid title="What must line up for a tool to run"
flowchart TD
  Ask["Agent asks for a tool"] --> Role["Role permissions<br/>may they use MCP / connectors?"]
  Role --> Share["Resource share<br/>view / use / edit on toolbox"]
  Share --> Restrict["Restrictions<br/>connector or tool allow/block"]
  Restrict --> Run["Tool runs<br/>through their connections"]
```

- **Roles** decide which *actions* someone may take in the app (create a connection, manage SSO, and so on).
- **Restrictions** can still hide specific connectors or tools from a role, even if the role has `connector:view`.
- **Sharing** on a toolbox or custom connector decides whether someone can view, use, or edit that particular resource.

Someone needs the permission *and* any required share *and* to clear restrictions before a tool is actually usable through MCP.

## Good to know

- Each person holds exactly one role. Promoting someone replaces their role rather than adding to it.
- Changes apply immediately — including to people who are already signed in, and to API tokens or your organization's MCP endpoint when it runs as them.
- Built-in roles can't be edited. Copy the idea into a custom role instead.
- The last **Org Owner** can't be removed or demoted until someone else is an Owner.
- New joiners (invite, verified-domain join, or SCIM without a group mapping) get **Member** by default unless you choose another role.
- **Guest**, **Billing Admin**, and **Auditor** are free seats — they don't consume a billable seat.

:::callout{type="tip"}
Start from **Member** or **Guest** and add only what the job needs. It's easier to grant one more permission later than to unwind a broad Admin assignment.
:::

## Related

- [Invite and manage people](/guides/members/invite-and-manage-people)
- [Organize people into teams](/guides/members/teams)
- [Set connector and tool restrictions](/guides/governance/set-restrictions)
- [Provisioning members with SCIM](/guides/sso/scim-provisioning)