Roles and teams
The four roles (viewer, responder, admin, owner) and exactly what each may do, the minimum role of every API route, the team hierarchy, and how approvals follow it.
Roles
Roles are global and ordered; each includes the ones below it. Whatever their role, a team's lead manages that team and the teams under it. The admin token acts as an owner.
| Role | May |
|---|---|
owner | Everything an admin may, plus: the licence (install, replace, check, remove, services always covered); make people admins or owners and change or remove them; give someone a password; take over as the Keychain's home |
admin | Everything a responder may, plus: connections; the policy and escalation; request more autonomy (approved by others); the fix mode; resume after a halt; the estate, discovery and Study; learned patterns; branding; e-mail, single sign-on and sign-in rules; add viewers and responders and manage every team; the business report and its figures; the usage statement; the Keychain and installs (make the home, add sites, pair, vouch, take off, choose what it carries, keep a member's own copy, hand the home over) |
responder | Everything a viewer may, plus: halt 3AM, withdraw an approval request, record what the team did on an incident. Asked to approve fixes on their teams' services |
viewer | See incidents, approvals, the digest, the estate, the audit log, connections (never their secrets), the policy, 3AM Doctor, the Keychain and installs; export; change their own name, handles, time zone and appearance. Not the people list, the business report or the sign-in settings. Never asked to approve |
Guards: only owners give or change the owner and admin roles; the last owner can't be demoted, disabled or
removed; a person may change their own name and handles (PUT /v1/me), never their own role.
Every route has a minimum role
Checked by the server on every call (identity.RULES). An unlisted read needs viewer; an unlisted change needs
admin, so a new endpoint is closed by default. A refused call answers 403 with the role it needs.
| Route | Needs |
|---|---|
Any other GET | viewer |
GET /v1/users, /v1/impact, /v1/lookback, /v1/settings/*, /v1/licence/usage | admin |
GET /v1/keychain, GET /v1/licence/installs | viewer |
POST /v1/halt, /v1/approvals/<id>/withdraw, /v1/episodes/<id>/team, /v1/learning/label | responder |
POST /v1/resume | admin |
POST /v1/keychain/*, POST /v1/licence/installs/* | admin (take-over: owner) |
POST /v1/licence, /v1/licence/check, /v1/licence/redeem, PUT /v1/licence/services, DELETE /v1/licence | owner |
POST/PUT/DELETE /v1/teams/*, PUT /v1/me | viewer (checked per team / yourself) |
| Any other change | admin |
Teams
- A team may sit under a parent team; it has a lead and members; it owns services.
- A lead manages their team and every team below it: members, sub-teams, services. Admins and owners manage every team.
- Moving a team needs authority over its new parent; a team can't be moved under itself. Removing a team moves its sub-teams up to its parent.
Approvals follow the hierarchy
When policy names no approvers for a service, 3AM asks the team that owns it (from its service list, or a team named like the estate's owner), in this order:
- the team's responders, by e-mail;
- its lead;
- the leads of the teams above it.
People are reached on their handles for each channel ({"chat": "U123", "pager": …, "phone": …}). Viewers are
never asked. Whether only those people can answer is the channel's: give every approval channel an approvers list, or
put services in teams.
API
| Call | Who | Purpose |
|---|---|---|
GET /v1/me, PUT /v1/me {name, handles} | signed in | Who you are, your role and teams; your own name and handles |
GET /v1/users, POST /v1/users, PUT/DELETE /v1/users/<id> | admin | People: e-mail, name, role, status, handles |
GET /v1/teams | viewer | Teams, flat and as a tree |
POST /v1/teams, PUT/DELETE /v1/teams/<id> | admin, or a lead above it | Teams: name, parent, lead, members, services |
Audit events: identity.user_added, identity.user_changed, identity.user_removed, identity.team_saved,
identity.team_removed.
Single sign-on
Sign in with your identity provider (OIDC, PKCE) or your directory (LDAP, Active Directory); group mappings to roles and teams; staying in step; mixed mode; how 3AM finds out your directory by itself.
Approvals
Where people approve fixes, who may, how requests escalate, and when two approvers are needed.