Skip to content
Docs menu

Organisations, members and roles

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.

View .md

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); 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

Your first organisation is made at sign-up (see Sign in). 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

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

/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

  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 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. 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

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)

/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".

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).

Permission profiles

/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.

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.