Organizations, teams and access

Everything you run belongs to an organization; the people who may act on it are members of its teams; what each of them may do is a small set of grants. This chapter is the user's side of that model: creating and switching organizations, inviting teammates, and assigning the four permissions from Access (/<org>/access). The operator's control-plane-wide roles are in Administering the control plane.

The model

PLAINTEXT

organization ─┬─ teams ──── teammates (people)
              ├─ workspaces ── projects ── environments ── services …
              └─ servers, networks, TLS, repositories …

Thing	What it is
Organization	The unit of ownership and billing. Servers, projects, networks, certificates and repositories all belong to exactly one. A person can belong to several and switches between them from the header menu (View all organizations → `/organizations`).
Team	A group of people inside one organization. Membership is how a person becomes part of the organization at all — you are a member because a team has you. Every organization starts with a Default Team.
Workspace	A folder for projects inside the organization, with its own name and default. Every organization starts with a Default Workspace. Workspaces filter the Projects list; they do not carry their own permissions.
Grant	One row saying subject S holds permission P on resource R: the subject is a user, a team or an organization; the resource is the organization or a team.

The four permissions

Permission	App name	What it unlocks
`organization:own`	Organization owner	Everything a manager can, plus the owner-only acts: server capacity, registration keys, TLS opt-ins and the Compose opt-ins under Manage Organization, invitations that carry explicit grants, and creating or revoking grants.
`organization:manage`	Organization manager	Day-to-day work on anything in the organization — projects, environments, deploys, servers, networks, managed databases, variables — and inviting to any team.
`team:own`	Team owner	Owner of one team: the same as team manager today, kept distinct so a team can have a responsible owner.
`team:manage`	Team manager	Inviting to, and revoking invitations for, that one team.

How they combine:

Owner implies manager. A check for organization:manage passes with either grant; a check for organization:own needs the owner grant itself.
Organization grants reach every team. An organization owner or manager may act on any team in the organization; a team grant reaches only its team.
Grants flow through membership. A grant to a team applies to everyone in it; a grant to the organization as subject applies to everyone in any of its teams. Most organizations need nothing beyond the grant an invitation carries.
Administrators bypass all of this. A user whose control plane role is superadmin or admin (see Administering the control plane) passes every organization check without a grant row.
The last owner cannot be removed. Revoking the only organization:own grant on an organization is refused.

Visibility follows the same rules in the database, not in the app: a list shows what your grants reach, and nothing else.

Before you begin

To invite: manager rights on the team (a team owner or manager, or an organization owner or manager).
To attach explicit grants to an invitation, or to add and revoke grants: organization owner.
Outbound email configured on the control plane — an invitation is an email, and without a mailer it is refused rather than created silently (Control plane).

Create or switch an organization

Header organization menu → New, or /organizations → New. Name it. On TurboPanel High Availability the first organization from sign-up is called My Organization; on self-hosted, install creates Root Organization.

You become its owner (organization:own) and the owner of its Default Team, with a Default Workspace ready for projects.

Switch with the header menu (searchable once you belong to more than one); Manage next to an organization opens Manage Organization — the record's name, and the owner-only opt-ins.

Renaming is Manage Organization → Organization (managers may save). Names follow the display-name rule: no control characters, bounded length. Organizations are not deleted from the app in this release.

Invite a teammate

Access → Invite a teammate.

Pick the Team and enter the Email → Send invitation. One pending invitation exists per team and address; a second is refused (invitation_pending) until the first is accepted, revoked, or expires.

The invitee receives a link good for 7 days. Pending invitations lists every unexpired one across the organization's teams with who sent it and when it expires; Revoke invitation ends it before it is used.

The invitee opens the emailed link, which lands on Accept invitation and never accepts by itself. What it shows depends on who is opening it:

Already has an account on the invited address: they are taken to sign in, return to the page, and press Accept invitation.
No account on that address yet: the page asks them to Create a password and press Join (the button reads Join plus the organization's name). That one step creates the account (the address counts as verified, because the emailed link proves it), accepts the invitation and signs them in, with no confirmation step and no personal organization of their own. It works even while public sign-up is disabled.
Signed in as someone else: the page says This invitation is for another account and offers Switch account, which signs them out and returns to sign in with the invited address.
Link already accepted: the page says so and points to sign in. Expired or withdrawn: it says which and asks them to request a new invitation from whoever sent it. A link replaced by a re-sent invitation says it is not valid anymore: use the newest email.

The accepted invitation creates the team membership and, by default, an organization manager grant to the new member. An organization owner may instead specify the grants an invitation carries (the API's grants field: any grantable permission on an entity inside the organization, checked at accept time); anyone else who tries is refused (grants_require_owner).

The address must match

An invitation is accepted only by an account whose email equals the invited address (case-insensitively). Forwarding the link to another address does not work; revoke and re-invite instead.

Members

Access → Members lists everyone with access to the organization: Name, email, a role badge (Owner, Manager or Member, the highest organization permission the person holds) and Joined date. A person counts as a member through a team in the organization or through a grant on it. Only owners and managers can see the list.

Remove on a row asks Remove <person> from this organization? They lose all access. Confirm.

The person's team memberships and every grant they hold inside the organization are deleted in one step. Their next request is refused and the organization drops out of their list. Their account, their sessions and their other organizations are untouched.

To leave yourself, use Leave organization on your own row (Leave this organization? You lose all access to it.). Anyone can leave.

Rule	What happens
Owners and managers may remove people	Anyone else is refused (`Forbidden`, 403).
Only an owner can remove an owner	A manager removing an owner is refused (`Only an owner can remove an owner`, 403).
The last owner cannot be removed or leave	Refused (`Cannot remove the last owner of an organization`, 409). Make another person an owner first.
Removal is recorded	The audit log records `member.remove`, and the person is told their access was revoked.

When the organization has turned on Ask people to confirm it is them before permanent actions, removing a person (and leaving) first asks you to confirm your password; see Account security.

Assign a permission

Access → Access grants. Owner-only; others see You don't have permission to manage access on this scope.

Choose the Grant target: the Organization, or one Team. The table shows the Active allow grants on that target: subject kind, subject, permission.

Add grant: Subject kind (user, team or organization), Subject ID, and the Permission — organization:own / organization:manage on an organization target, team:own / team:manage on a team target. Create grant.

Revoke grant on a row removes it (confirmation: Revoke this access grant?). Revoking the last owner grant on an organization is refused.

Subject IDs are the account, team or organization ids. The teams are in the Team picker, and a person's id is in the Members list (GET /organizations/:id/members); your own is in GET /api/client/v1/authn/session. Grants are allow-only — there is no deny row. To take a person's access away entirely, remove them under Members rather than revoking grants one by one.

Reference

Item	Value
Permissions on grants	`organization:own` · `organization:manage` · `team:own` · `team:manage`
Grant targets	`organization`, `team` (the API also accepts the resource tree — workspace, project, environment, service, server, hosting, variable, managed, container, tls)
Subjects	`user` · `team` · `organization`
Invitation lifetime	7 days; one pending per team + address
Default invitation grant	`organization:manage` on the organization
Defaults on creation	Default Team (creator `team:own`), Default Workspace, creator `organization:own`
Control plane roles	`superadmin`, `admin` bypass organization grants; `user` does not — see Administering the control plane

Errors

Code	Status	Meaning
`invitation_pending`	409	That address already has a live invitation to that team.
`email_unavailable`	503	The control plane cannot send mail, so the invitation was not created.
`grants_require_owner`	403	Only an organization owner may attach explicit grants to an invitation.
`Invalid invitation grants`	400	A grant in the invitation names a permission or target that does not fit (for example a team permission on the organization).
`Forbidden`	403 (accept)	The signed-in account's email is not the invited address.
`gone`	410 (accept)	The invitation expired, was revoked or was already used — or its team or organization no longer exists.
`invalid_grant`	400 (accept)	The invitation's stored grants no longer fit the organization.
`Not found`	404	No pending invitation, or no grant, with that id.
`Entity not found`	404	The grant target is not in this organization.
`… may only be granted on organization entities` / `… on team entities`	400	The permission does not fit the target kind.
`Cannot remove the last owner of an organization`	409	Revoke would leave no `organization:own`. A team has the same rule: `Cannot remove the last owner of a team`.
`Only an owner can remove an owner`	403	A manager tried to remove an owner from Members. Ask an owner.
`You don't have permission to manage access on this scope.`	403	Grant management needs `organization:own` on the target.

Account security — the account that holds these memberships.
Projects and environments — workspaces and what a manager does with them.
Administering the control plane — control plane roles and sign-up policy.
Accounts and access — the invitation sequence diagram and provider configuration.

On this page