Documentation

Teams, roles and sharing

Organisations, viewer to owner, teams, sharing machines and skills with a team or a person, invitations, what keys never do.

Organisations

Every account starts with a personal organisation. A team gets a shared one: organisation switcher → Create organisation, with a name and a short URL slug. Machines, skills, deliveries, jobs, alerts, channels and API keys belong to one organisation; creating another does not move existing machines, and a machine is paired into one organisation at a time. The dashboard shows one organisation at a time under /o/<slug>, with the switcher in the sidebar; the one you used last is where you land next time, and where skillhook cloud login starts. Someone alone in their personal organisation never needs anything on this page: they own everything in it.

Roles

Four roles, each including the ones below it. A role applies to everything the whole organisation sees; a machine, skill, hosted URL or channel can be restricted to some people and teams (Sharing). A machine's mode and its allow and deny lists still apply on top (see Machines and pairing). An API key acts as the role of its scope, never as owner and never above its creator's role.

RoleCanKey scope
viewerSee the machines, skills, deliveries and jobs shared with the whole organisation (or with them).fleet:read
memberEverything a viewer sees, and run and test skills, answer agents, replay deliveries, pair machines, create teams and their own API keys.fleet:run
adminEverything on every machine, skill, hosted URL and channel (shared or not), settings, API keys, billing; invite and remove members below admin.fleet:admin
ownerEverything an admin does, and make and remove admins and owners and transfer ownership. An organisation always keeps one.none
  • Members pair machines (and administer the ones they pair), create teams and their own API keys, up to fleet:run. Admins and owners add notification channels, manage every key and invite people.
  • Admins change roles below admin (viewer and member) and remove viewers and members; only an owner makes or removes admins and owners, or transfers ownership by making someone else owner. Nobody gives a role, a key or an access above their own.
  • An organisation needs at least one owner: the last owner cannot step down or be removed until someone else is made owner.
  • Anyone can leave an organisation themselves; admins and owners remove others.

Teams

A team is a group of members inside the organisation (Team → New team), to share machines, skills, hosted URLs and channels with all of them at once. Any member creates one and maintains it; admins and owners manage every team. Only members of the organisation are in its teams: leaving the organisation leaves its teams too, and deleting a team ends what was shared through it, never the people.

Team roleCan
memberGets what is shared with the team.
maintainerAlso adds and removes the team's people and renames or deletes it.

Sharing

Every machine, skill, hosted URL and notification channel has a Share button. It is seen either by everyone in the organisation at their role (the default, and how everything was before teams), or it is restricted: only its creator, the admins and owners, and the people and teams it is shared with see it, with everything about it (a restricted machine's jobs, deliveries, health and commands; a restricted skill's jobs and deliveries). A skill on a machine you cannot see is out of sight with it, and a hosted URL follows its skill.

A share gives a team or a person read, write or admin access. Your access is the highest of your role on what the whole organisation sees (viewer read, member write, admin and owner admin), admin on what you created, and every share to you or a team you are in. A viewer never gets more than read. Whoever has admin access to something shares it, never above their own access.

AccessOn a machineOn a skill
readSee it, its jobs and deliveriesSee it, its jobs and deliveries
writeAlso run and test skills, answer agents, replayAlso run it, answer its agents, replay its deliveries
adminAlso configure, rename, disconnect and share itAlso edit it, its hosted URL, and share it

The database decides it (row-level security through can_access), so the dashboard never reads a row you may not see; the API applies the same rules to keys. Shares are audited (grant.set, grant.removed, grant.visibility_changed).

Invitations

Team → invite by email with a role (viewer or member; owners also invite admins, and promote owners afterwards) and, optionally, the teams they join on accepting. The invitation is emailed and its link is always shown too, so you can send it yourself when email is not enabled on the deployment. an invitation is valid seven days, works once, and must be accepted while signed in with the invited, verified email address; another address is refused. Resending issues a new link with a fresh seven days and the old link stops working; withdrawing deletes it. Open invitations count towards the plan's people limit until they are accepted or withdrawn (see Plans and limits). An organisation can send at most 20 invitation emails an hour; its admins still get the links.

API keys never manage access

Keys, members, invitations, roles, pairing machines and new notification channels are changed by a signed-in person on the dashboard only. A key can read the team (list_members: people, roles and teams; admin keys also see pending invitations) and never invite, change a role, remove anyone or create another key, so a leaked key can neither widen nor outlive its access, and revoking it ends everything it could do. A key belongs to the organisation, not to the person who made it: it records them and carries their access (what is shared with them, capped at the key's scope, and lowered when their role is). When they leave, it keeps working with its scope's role (a read or run key on what the whole organisation sees, an admin key as an admin), and admins see it under Settings → API keys ("its creator left the organisation") to revoke it. See API keys and scopes.

The audit log

Every mutation is audited: who (a person, an API key, a machine, or the system), what, and on what: commands sent, machines paired, renamed and disconnected, skills saved and deleted, hosted URLs turned on and off, settings, members, invitations, roles, keys created and revoked, channels, alerts dismissed, problem reports. Payloads, answers, SKILL.md contents and report text are never in it, only identifiers and flags. Admins read it under Audit log or with list_audit_log, filtered by an exact action or a prefix ending in a dot.