Organizations, projects and teams

Hierarchy

• Organization (org) — the top level: billing/quotas, members, teams, probes, SSO. Everything else lives inside it.
• Project — a specific application or service: it has its own DSN, its own issues, its own monitors, and so on.
• Team — a group of an organization’s members that can be granted access to a subset of projects, without handing out an organization-wide role.

Roles

Roles are assigned at the organization level and apply across all its projects:

An organization’s last owner cannot be demoted or removed — the system always protects against an organization ending up with no owner.

Instance admin

Separately from organization roles, there’s an instance administrator flag (users.is_instance_admin) — exactly one per instance, unrelated to any role in any organization. It’s assigned automatically to the first user registered on the instance.

The instance administrator configures and removes SSO for organizations — that capability isn’t granted by the owner role, only by this flag (see the roles table above). While other users exist on the instance, the instance administrator’s account cannot be deleted until the role is transferred to one of them — otherwise SSO for every organization would become unreachable to everyone. If the instance administrator is the only user on the instance, they can delete their own account freely: there’s no one to transfer the role to, and the next person to register becomes the administrator automatically.

Transfer the role from the “Instance admin” section on /profile: enter the email of an existing instance user and confirm the transfer. Once confirmed, the role moves to the recipient immediately, and the previous administrator loses access to SSO configuration and the ability to transfer the role again.

Recovery if access to the instance administrator’s account is lost: if only the password is forgotten, a regular password reset restores access — the administrator’s account still cannot be deleted while other users exist on the instance. If the account is completely unreachable, an operator with access to the instance database assigns a new administrator directly, in one transaction — BEGIN/COMMIT are required: psql autocommits by default, and without them a typo in the email after the first UPDATE silently leaves the instance with no administrator at all:

BEGIN;
UPDATE users SET is_instance_admin = false WHERE is_instance_admin;
UPDATE users SET is_instance_admin = true WHERE email = '<email>';
COMMIT;

Before COMMIT, verify each UPDATE reported UPDATE 1 — UPDATE 0 on the second command means a typo in the email, and committing in that state leaves the instance with no administrator. The partial unique index one_instance_admin prevents two users from ending up as administrator at once.

Inviting members

The “Settings” → “Organization” → “Members” page (/orgs/{id}/settings, owner/admin only) has a table of current members (email, role, change-role, remove) and an invite form:

1. Enter the invitee’s email.
2. Pick a role — member or admin (the owner role cannot be granted through an invite — it can only be assigned to an existing member afterward).
3. Click “Invite”.

If the server has no SMTP configured, the invite is still created but no email is sent — instead, the page shows a direct invite link once, which you forward to the person manually (it’s not shown again).

Until it is accepted, an invitation is listed under “Awaiting acceptance” on the same page and can be revoked there — mistype an address, and revoking kills the link before a stranger can use it. Accepting removes the invitation from the list and adds the member.

What happens next depends on the instance’s registration mode (GOTCHA_REGISTRATION_MODE, see Configuration):

• open — self-registration is always open; an invite is just a way to add someone with a specific role right away;
• invite (default) — self-registration closes once the instance has its first user; joining afterward requires a valid invite link (or OAuth/SSO, if a pending invite exists for that email);
• closed — self-registration is closed entirely, except for the instance’s very first user.

Teams

The “Settings” → “Organization” → “Teams” page (/orgs/{id}/teams, owner/admin only) lets you group members and grant them access to specific projects without changing their organization-wide role.

Creating a team:

1. Click the “+” next to the page heading — a “Create team” modal opens.
2. Enter a Slug (a short identifier, e.g. backend) and a Name (the display name, e.g. “Backend”).
3. Save.

Each team gets its own card on the page, with two lists and forms underneath. The card heading carries a “Rename” button: it changes the display name without touching members or attached projects. The slug stays as it is — it is used in URLs and in access grants.

Inside the card:

• Members — a table of current members, an add form with a dropdown (listing only organization members not yet in this team), and a remove button on each row.
• Projects — a table of attached projects, an attach form with a dropdown (listing only organization projects not yet attached), and a detach button on each row.

Only someone already in the organization can be added to a team; attaching a project to a team doesn’t change what organization owners/admins can see — they already see every project.

Roles and access

Being on a team attached to a project — an operator, in the table below — is what lets a member actually run the monitoring day to day, without promoting them to admin and handing them every other project in the organization along with it. Org owners and admins automatically qualify as operators on every project too, since they already have full access.

“Viewer” here isn’t a role of its own — it’s what CanAccessProject grants to anyone who can already see the project (an org owner/admin, or a plain member on an attached team), before touching the operator predicate at all. In other words, every operator is also a viewer, and every admin and owner is also an operator: the columns are cumulative, not exclusive tiers.

What team membership buys a member, in short: everything about running monitoring day to day on that project’s monitors, maintenance windows, status pages, alert rules, and metric alerts — the operational surface, without an organization-wide role. What still requires admin (or owner): alert channels, because their recipient and secret (a bot token, an SMTP address, a webhook URL) are credentials and personal data, not operational settings; whether a status page is actually public, because that’s a decision about what the organization shows the world, not how monitoring is run; and project settings and everything at the organization level, unchanged from before.

What’s next

• SSO and social login — single sign-on instead of a password.
• Probes — another owner/admin organization page.
• Configuration — registration modes and other server settings.