---
title: Organisations, members and roles
description: Create and switch organisations, invite members, change their roles, understand what each role may do, and set a key group's permission profile for the venom CLI.
section: cloud
order: 12
audience: [user, operator]
sources: [services/nodejs-cloud/app/(console)/(shell)/orgs/new/page.tsx, services/nodejs-cloud/app/(console)/(shell)/org-actions.ts, services/nodejs-cloud/components/shell/OrgSwitcher.tsx, services/nodejs-cloud/components/workspace/switch-path.ts, services/nodejs-cloud/app/(console)/(shell)/settings/members, services/nodejs-cloud/app/(console)/(shell)/settings/teams/page.tsx, services/nodejs-cloud/app/(console)/(shell)/permissions, services/nodejs-cloud/components/console/rbac.ts, services/nodejs-cloud/components/console/access.ts, services/nodejs-cloud/components/permissions]
features: [cloud.console-orgs, cloud.console-permissions]
---

An organisation is everything one company has in Venom Cloud: its key groups, API keys, daemons, provider keys,
routing, usage, billing and members. A key group inside it owns keys, join tokens and daemons (not people; teams of
people are [org teams](/docs/cloud/teams.md)); a new organisation starts with one key group, `default`. The API keeps the
name `team` for a key group (`team_id`, `/api/admin/v1/teams`). People belong to an organisation with one role, and the console shows each
person only the pages that role may open.

## Create an organisation {#create}

Your first organisation is made at sign-up (see [Sign in](/docs/cloud/console-sign-in.md#sign-up)). For another one,
open the org switcher at the top left and choose "Create organisation", which opens `/orgs/new`:

1. Enter a name of 2 to 80 characters.
2. Press Create. You become its owner, the console switches to it and opens the first-run checklist.

Only members who signed in with email (Clerk) can create organisations. The operator creates organisations
("tenants") under `/settings/teams` instead. A legacy key group session cannot create one.

## Switch organisations {#switch}

The org switcher lists every organisation you belong to. Picking one re-issues your session for it after
checking your membership; the old session is revoked everywhere, so a copy of it cannot act in the old
organisation. You stay on the same page when your role in the new organisation may open it, otherwise you land
on `/dashboard`.

The same switcher is on every signed-in screen:

- In the Admin console and on Home it sits at the top of the sidebar (in the menu drawer on a phone).
- In every other app (Notes, Tasks, Flags, Forms, Experiments, Incidents, People, Funnel, Calendar, Support, Chat)
  it is the organisation's initial at the top of the app rail. On a phone it is the first item of the bottom bar.
- From anywhere, press ⌘K (Ctrl+K) and choose **Switch organisation…** to list the other organisations, or type
  the organisation's name.

Switching from an app keeps you in that app, on the nearest page that holds nothing of the old organisation. A
list or view stays where it is (`/calendar`, `/tasks/my/created`, `/people/companies`). A page for one item goes
to its list: `/tasks/issue/ENG-12` lands on `/tasks`, a note on the vault, a deal on Funnel's board. If the page
has unsaved changes, you are asked first, as when you leave the page. Public pages (booking pages under `/meet`,
forms under `/f`, these docs, sign-in) don't show the switcher.

- An organisation that requires single sign-on sends you through its identity provider first (owners excepted).
- A session that came from one organisation's SSO never opens another organisation.
- MSP staff also see the client organisations they may enter; entering one is audited in both organisations.
- The operator's switcher is a listing filter (a cookie, 12 hours): it narrows what the pages show and never
  limits what the operator may change.

## Members {#members}

`/settings/members` lists the organisation's people, their roles, who is online, and pending invitations. People are
never limited or charged per seat. Reading it needs `members:read`; inviting, changing roles and removing need
`members:manage` (owner or admin).

### Invite someone {#invite}

1. Press Invite (the checklist's link is `/settings/members?invite=1`).
2. Enter their email and pick a role.
3. Send. They get an email with a link to `/auth/clerk/sign-up`; the role applies when they accept.

"Revoke invitation" makes the emailed link stop working. Invitations need Clerk sign-in and an organisation created through it;
people who sign in another way are added by the operator or by single sign-on.

### Change a role or remove a member {#change}

- Change a role in place from the member's row. Changing someone to or from owner asks first.
- An invitation never makes an owner: owners are made from the members list, by an owner. An admin can't make or
  demote an owner.
- An organisation always keeps at least one owner.
- "Remove" ends the member's access at once; their API keys keep working until you revoke them under
  [API keys](/docs/cloud/console-api-keys.md). On your own row the action is "Leave organisation".
- A removed member is signed out on their next page load: the role is re-read on every request.

Every change is audited (`member.invited`, `member.role_changed`, `member.removed`, `member.joined`).

## Roles {#roles}

| Role | What it may do |
|---|---|
| `owner` | Everything, including billing, single sign-on and making others owners. |
| `admin` | Everything except billing and single sign-on: members, keys, providers, daemons, routing and data settings. |
| `developer` | Creates API keys, enrolls and runs daemons, changes routing, reads logs and logged content. |
| `billing` | Plan, seats and usage. No keys, daemons or logs. |
| `viewer` | Read-only: daemons, keys, providers, routing, logs and usage. |

The permissions behind them, which the console and the admin API both check:

| Permission | owner | admin | developer | billing | viewer |
|---|---|---|---|---|---|
| `org:read`, `members:read`, `usage:read` | yes | yes | yes | yes | yes |
| `keys:read`, `providers:read`, `daemons:read`, `routing:read`, `logs:read` | yes | yes | yes | no | yes |
| `keys:write`, `daemons:enroll`, `daemons:manage`, `routing:write`, `content:read`, `audit:read` | yes | yes | yes | no | no |
| `org:manage`, `members:manage`, `providers:write`, `content:settings` | yes | yes | no | no | no |
| `billing:read` | yes | yes | no | yes | no |
| `billing:manage` | yes | no | no | yes | no |
| `sso:read` | yes | yes | no | no | no |
| `sso:manage` | yes | no | no | no | no |

Two more kinds of principal exist. The operator (the deployment's admin token, or an email in
`VENOM_CLOUD_CLERK_ADMINS`) may do everything in every organisation. A legacy key group member (GitHub or Clerk
mapped to one key group) has the developer permissions inside that key group only. An MSP session gets the client's grant:
a permission outside it is refused even when the role has it.

A page your role can't open shows a "no access" notice naming the permission instead of an error, and the nav
hides its link.

## Tenants and key groups (operator) {#teams}

`/settings/teams`, "Tenants & key groups", is for the operator only. A tenant is an organisation; its key groups
own keys, join tokens and daemons and can share daemons with the other key groups of their tenant.

| Action | Fields |
|---|---|
| New tenant | Name, up to 80 characters |
| New key group | Tenant, Name (up to 80 characters, unique in the tenant) |
| Delete key group | type the key group's name to confirm |

Each tenant card shows its id (with a copy button), its key groups, and badges for "Clerk" (linked to a Clerk
organisation), "own keys only" (the cloud's platform keys are off) and "content logging off".

### Link a tenant to Clerk {#link-clerk}

A tenant made here has no Clerk organisation, so its Members page can't send invitations. When Clerk sign-in is
configured, its card has **Link to Clerk**:

- Leave the id empty and Clerk creates an organisation named after the tenant. Then invite members from
  Members (`/settings/members`, with the org picked in the switcher).
- Or paste the id of an organisation that already exists in Clerk (`org_…`). Its members join the tenant the
  next time they sign in, with the role their Clerk membership maps to.

A tenant is linked once, and an organisation belongs to one tenant. Each link is written to the tenant's audit
log as `org.clerk_linked`. The API is `POST /api/admin/v1/tenants/{id}/clerk`
([Admin API](/docs/cloud/api-admin-access.md)).

## Permission profiles {#permissions}

`/permissions` sets what venom may do on a key group's machines: commands, files, web domains and tools to deny or
always ask about, optionally per repository, plus the permission modes, the OS sandbox and the web and browser
tools. The rules travel in the key group's signed policy, so they only ever tighten what members set themselves:
an organisation policy has no allow rules, and its deny and ask rules sit in front of every local rule, mode
and session grant.

Reading needs `routing:read`; saving needs `routing:write` (owner, admin, developer). With several key groups, pick
one in the Key group pills (`/permissions?team=<id>`).

1. If the page says "Signing isn't set up", an owner or admin presses **Set up signing**: it creates the
   organisation's policy-signing key, kept sealed in the cloud.
2. Edit the rules in the form, or switch "Edit as" to JSON.
3. Test a call: pick a tool, give its argument (a command, a path, a URL) and a repository remote; the tester says
   `deny`, `ask` or `none` for the unsaved draft, and which rule and profile decided.
4. Press **Save and sign**. The page answers "Policy #N signed". Members get it when venom starts, or at once
   with `venom policy sync`.

| Section | Key in the policy | What it holds |
|---|---|---|
| Rules for every checkout | `deny`, `ask` | rules like `bash(terraform apply:*)`, `read(~/private/**)`, `web_fetch(domain:*.pastebin.com)`, `edit(migrations/**)` or a whole tool such as `mcp__github` |
| Repository profiles | `repos` | up to 50 profiles: 1 to 20 repository patterns each (`github.com/acme/web`, `acme/web`, `*` in a segment, `**` across), a note, and deny or ask rules added after the key group's |
| Permission modes | `modes` | limit the modes members may switch to, and the default mode; a higher mode drops to the highest allowed one, sudo is refused |
| OS sandbox | `sandbox` | require it (every bash command sandboxed, `--no-sandbox` refused, bash denied where there is no sandbox), and the hosts sandboxed bash may reach, plus package registries |
| Web tools, Browser tools | `web`, `browser` | allow or turn off the web tools and driving a browser (`--chrome`, the extension) |

The cloud checks a profile as the CLI would before saving it, so a saved policy never stops venom from
starting: an unknown mode, a default outside the allowed modes, a malformed rule, a bad host or a profile
without patterns or rules is refused. Other policy keys (the MCP allowlist, contacts) are kept. Each save is
audited `policy.permissions_set` with the policy before and after. How the CLI applies a signed policy is in
[Policy](/docs/security/policy.md#signed).

## Troubleshooting {#troubleshooting}

| Message | Cause and fix |
|---|---|
| Invitations need Clerk and an organisation created through it. | The tenant was made by hand: the operator links it under Tenants & key groups, Link to Clerk. |
| Not available for this sign-in (on `/orgs/new`) | Only members signed in with email create organisations. Ask the operator. |
| Your role does not allow this. | Inviting, role changes and removal need `members:manage`. |
| All N seats are in use | The plan's seats, pending invitations included. Upgrade, or remove someone. |
| Signing isn't set up yet: use Set up signing at the top of the page. | The organisation has no policy-signing key. An owner or admin creates it. |
| Your role cannot change the key group's permissions. | Saving needs `routing:write`. |
| No key group to configure yet. | The organisation has no key group; the operator creates one under Tenants & key groups. |

## Related

- [Sign in](/docs/cloud/console-sign-in.md)
- [Single sign-on and SCIM](/docs/cloud/console-sso.md): group rules that set roles at sign-in.
- [API keys](/docs/cloud/console-api-keys.md): model access by role.
- [Policy](/docs/security/policy.md)
