Endpoints: Organizations, Teams & Invitations
Organizations
Section titled “Organizations”An organization, its members and its data export. Membership is org-scoped: deactivating or removing a member here leaves their other organizations and their account alone.
POST /v1/orgs
Section titled “POST /v1/orgs”Create an additional organization
Creates an organization owned (role owner) by the calling user. Requires a human session: an API key is already bound to one org. Returns 403 when a platform admin has turned off registration.allow_public_org_creation, unless the caller is a superadmin. The new org gets the mounted product’s starter content, as at registration.
Creating does not re-scope the session: as with accepting an invite, it writes the membership and leaves the cookie where it was. Follow it with POST /auth/session/switch on the new org_id. The dashboard does this itself, from the org switcher’s Create organization entry and, for an org-less account, from /onboarding.
Request body (application/json)
{ "name": "string"}Response 201 (application/json) — Organization created
{ "org_id": "8f2a...", "name": "Acme Corp", "role": "owner"}403— API-key principal; or public organization creation is off and the caller is not a superadmin
GET /v1/orgs/{org_id}
Section titled “GET /v1/orgs/{org_id}”Get organization info
One organization’s info. Requires membership in it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "org_id": "8f2a...", "name": "Acme Corp", "plan_tier": "free", "quota": { "monthly_budget_usd": 50 }, "invite_link_ttl_hours": 168, "created_at": "2026-01-01T00:00:00Z"}403— The caller does not belong toorg_id404— Organization not found
GET /v1/orgs/{org_id}/members
Section titled “GET /v1/orgs/{org_id}/members”List organization members
Every member of the org. Any role may call it.
nameis null until the user sets one withPATCH /auth/me.is_activeis org-scoped:falsemeans the account is deactivated in this org only (seePATCH /orgs/{org_id}/members/{user_id}).account_activeis the whole account’sUser.is_active. Only a platform admin changes it (PATCH /admin/users/{user_id});falseblocks login in every org.teamslists the teams the member is on, fromteam_members; any number, or none.
In the dashboard: Organization → Access → Members.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "members": [ { "user_id": "string", "email": "string", "name": "string", "role": "string", "is_active": true, "account_active": true, "created_at": "2026-01-01T00:00:00Z", "teams": [ "string" ], "provisioned_via": "scim" } ]}POST /v1/orgs/{org_id}/members
Section titled “POST /v1/orgs/{org_id}/members”Add an existing user to the organization
Adds an already registered user to the org at a given role. Requires the org’s admin role. To bring in someone who has no account yet, use POST /orgs/{org_id}/invites.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "role": "member"}Response 201 (application/json) — Member added
{ "user_id": "u2...", "org_id": "8f2a...", "role": "member"}200403— Forbidden404— No registered user with that email409— The user is already a member of this org
PATCH /v1/orgs/{org_id}/members/{user_id}
Section titled “PATCH /v1/orgs/{org_id}/members/{user_id}”Change a member’s role and/or org-scoped active status
Changes a member’s role, org-scoped active status, or both; send only what changes. Requires the org’s admin role.
role can never be set to owner here; transfer ownership directly instead, as with invitation links and SSO’s default_role. is_active is org-scoped: deactivating a member blocks their access to this org on their very next request and leaves their other orgs and their account-wide User.is_active alone. PATCH /admin/users/{user_id} is the account-wide equivalent.
In the dashboard: Organization → Access → Members, the row’s actions.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
Request body (application/json)
{ "role": "string", "is_active": true}Response 200 (application/json)
{ "user_id": "string", "email": "string", "name": "string", "role": "string", "is_active": true, "account_active": true, "created_at": "2026-01-01T00:00:00Z", "teams": [ "string" ], "provisioned_via": "scim"}| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | yes | |
email | string | yes | |
name | string | null | no | |
role | string | yes | |
is_active | boolean | no | Org-scoped — see Membership.is_active. Distinct from account_active. |
account_active | boolean | no | Account-wide User.is_active — deactivating this blocks login entirely, in every org, unlike the org-scoped is_active above. Editable only via PATCH /admin/users/{user_id} (superadmin), never through the org-scoped membership endpoints. |
created_at | string (date-time) | yes | |
teams | string[] | no | Names of every team (see models.teams.Team) this user belongs to in this org — populated from team_members, not stored on the membership itself. |
provisioned_via | "scim" | "sso" | "invite" | null | no | See Membership.provisioned_via. |
400— Targets the caller’s own membership403— Forbidden404—user_idis not a member of this org409— Would demote or deactivate the org’s only remaining owner
DELETE /v1/orgs/{org_id}/members/{user_id}
Section titled “DELETE /v1/orgs/{org_id}/members/{user_id}”Remove a member from the organization
Removes a member from the org. Requires the org’s admin role. Has the same guards as the PATCH: not the caller’s own membership and not the org’s only remaining owner.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
200204— No Content400— Targets the caller’s own membership403— Forbidden404—user_idis not a member of this org409— The target is the org’s only remaining owner
POST /v1/orgs/{org_id}/leave
Section titled “POST /v1/orgs/{org_id}/leave”Leave this organization
Removes the caller’s own membership. Any role may leave: this is the counterpart to the admin-only DELETE /orgs/{org_id}/members/{user_id}, which refuses to act on the caller. Requires a human session: an API key belongs to one org for life.
org_id and role live in the session cookie, and a session left on an org the caller no longer belongs to would get 403 everywhere. So the cookie is re-issued for another org the caller still belongs to, or for no org if that was the last one. The response says which (org_id/role null: the org-less state /onboarding handles).
An organization always keeps an owner. Its only owner decides first: hand_over names the active member who becomes owner, or lock locks the org. A locked org keeps its data until a platform admin unlocks or deletes it. A membership provisioned by SCIM or SSO can be left like any other, but the IdP re-creates it on its next sync: remove the user there instead.
In the dashboard: Account, Organizations tab, Leave.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json, optional)
{ "hand_over": { "key": "string" }, "lock": [ "string" ]}| Field | Type | Required | Description |
|---|---|---|---|
hand_over | object | no | org_id → user_id of the active member who becomes that organization’s owner. |
lock | string[] | no | org_ids to lock instead. A locked organization keeps its data; a platform administrator can unlock or delete it. |
Response 200 (application/json) — Left; the session is re-scoped to org_id, or to no org
{ "left_org_id": "8f2a...", "org_id": "3b17...", "role": "member"}403— API-key principal, or not a member of this org404—org_idis not the caller’s current org409— The caller is the org’s only owner and sent neitherhand_overnorlockfor it
POST /v1/orgs/{org_id}/members/{user_id}/reset-password
Section titled “POST /v1/orgs/{org_id}/members/{user_id}/reset-password”Reset a member’s password
Requires members:manage. Clears the member’s password, signs the account out of every session, then emails a single-use link, valid for 30 minutes, to choose a new one. The same link is returned once for handing over when the deployment sends no mail (the log mail backend).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
Response 200 (application/json) — Password cleared; reset_url is shown once, and emailed
{ "reset_url": "string", "expires_at": "2026-01-01T00:00:00Z"}400— The account authenticates through SSO403— Forbidden404—user_idis not a member of this org
POST /v1/orgs/{org_id}/members/{user_id}/reset-2fa
Section titled “POST /v1/orgs/{org_id}/members/{user_id}/reset-2fa”Disable a member’s two-factor authentication
Turns a member’s two-factor authentication off. Requires the org’s admin role. Clears their TOTP secret and recovery codes; they enroll again from scratch. For a member who lost both the authenticator device and the recovery codes.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}403— Forbidden404—user_idis not a member of this org
GET /v1/orgs/{org_id}/invites
Section titled “GET /v1/orgs/{org_id}/invites”List org invitation links
Every invite ever created for the org, including revoked and expired ones: the dashboard grays those out rather than hiding them. Never includes the token. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "invites": [ { "invite_id": "string", "role": "string", "email": "string", "created_by": "string", "created_at": "2026-01-01T00:00:00Z", "expires_at": "2026-01-01T00:00:00Z", "revoked": false } ]}POST /v1/orgs/{org_id}/invites
Section titled “POST /v1/orgs/{org_id}/invites”Create an org invitation link
Mints a reusable link, valid for the org’s invite_link_ttl_hours (default 168 hours, range 1 to 8760) or until revoked. Requires the org’s admin role. Anyone who opens it can register or log in and join at the given role. Never grants owner. The raw token and join_url are returned once.
Pass email to address the invitation to one person: only that account can redeem it, and it shows up for them under GET /auth/me/invitations without delivery of the link.
/invite/{token} is a dashboard page, so join_url is built from server.dashboard_base_url, then server.public_base_url, then this request’s origin. When the dashboard is served under a path prefix on the API’s host, set dashboard_base_url to its full public URL, including the prefix, or join_url drops it. The invitation email is sent only when one of the two is set. The dashboard’s own Invitations page builds the link from its address and does not use join_url.
In the dashboard: Organization → Access → Invitations.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "role": "member",}| Field | Type | Required | Description |
|---|---|---|---|
role | string | no | |
email | string (email) | null | no | Address this invitation to one person. Two effects, both deliberate: the link stops being bearer-only — accepting it requires being signed in as that address — and the invitation becomes discoverable, listed by GET /auth/me/invitations for whoever owns that address, so joining a second org no longer depends on someone pasting them a URL out of band. Left None, the invite keeps its original semantics exactly: a reusable link anyone who holds it can redeem, discoverable by nobody. |
Response 201 (application/json) — Invite created; save join_url now
{ "invite_id": "string", "token": "string", "join_url": "string", "role": "string", "email": "string", "created_at": "2026-01-01T00:00:00Z", "expires_at": "2026-01-01T00:00:00Z"}403— Forbidden
DELETE /v1/orgs/{org_id}/invites/{invite_id}
Section titled “DELETE /v1/orgs/{org_id}/invites/{invite_id}”Revoke an org invitation link
Stops the link from being used again. Memberships already created through it stay. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
invite_id | string | yes |
200204— No Content403— Forbidden404— Invite not found
GET /v1/orgs/{org_id}/export
Section titled “GET /v1/orgs/{org_id}/export”Download all of this organization’s data
Streams all of the organization’s data as one JSON archive: the organization, its members, teams, roles, invitations, API keys, notification channels, SSO and SCIM settings, usage and audit events, then every section a mounted product adds. Secret fields (key and password hashes, encrypted credentials, webhook URLs) are left out. Requires org:export (admins and owners).
In the dashboard: Audit log, Export organization data.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "format": "opentremor-org-export/1", "org_id": "3b17...", "exported_at": "2026-10-19T08:00:00+00:00", "sections": { "organization": [], "members": [] }}401— Unauthorized403— Forbidden
A role is what a membership, an invitation, an API key or a SCIM group mapping stores. Four built-in roles form a ladder (viewer, member, admin, owner); each holds every permission whose default role it reaches. An org can add custom roles, named lists of permissions referenced as custom:<slug> anywhere a built-in role is accepted. Permissions are resolved on every request, so a change to a role applies at once to everyone holding it.
Two built-in roles sit off the ladder. auditor holds every permission marked read_only in GET /permissions and nothing that changes state: give it to a security team or to an API key that feeds a SIEM from GET /metrics/audit/export (OpenTremor-platform#0019). pipeline, for API keys only, holds what a CI job or an agent needs to run the product’s workflow and nothing else; it is the default role of POST /auth/keys, and giving it to a person returns 422 (OpenTremor-platform#0029).
No escalation: creating, changing or assigning a role returns 403 when it would grant a permission the caller does not hold. Superadmins are exempt.
GET /v1/orgs/{org_id}/roles
Section titled “GET /v1/orgs/{org_id}/roles”List the organization’s roles
Built-in and custom roles. Requires roles:read (member by default). Each built-in role carries a fixed description. key_only: true marks a role only an API key may hold (pipeline).
In the dashboard: Organization → Access → Roles.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "roles": [ { "role_id": "string", "name": "string", "description": "string", "permissions": [ "string" ], "builtin": true, "key_only": false } ]}POST /v1/orgs/{org_id}/roles
Section titled “POST /v1/orgs/{org_id}/roles”Create a custom role
Creates a custom role: a named list of permissions. Requires roles:manage (admin by default). role_id is custom: plus a slug of name, unique in the org; use it anywhere a built-in role name is accepted. The caller must hold every permission the role grants.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "name": "string", "description": "string", "permissions": [ "string" ]}| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
description | string | null | no | |
permissions | string[] | yes | Declared permission names (GET /permissions). |
Response 201 (application/json)
{ "role_id": "string", "name": "string", "description": "string", "permissions": [ "string" ], "builtin": true, "key_only": false}| Field | Type | Required | Description |
|---|---|---|---|
role_id | string | yes | What a membership, key, invitation or SCIM mapping stores: custom:<slug>, or a built-in role’s name. |
name | string | yes | |
description | string | null | no | |
permissions | string[] | yes | |
builtin | boolean | yes | A built-in role — listed for completeness, not editable. |
key_only | boolean | no | Only an API key can hold this role. |
403— The role would grant a permission the caller does not hold
PATCH /v1/orgs/{org_id}/roles/{role_id}
Section titled “PATCH /v1/orgs/{org_id}/roles/{role_id}”Change a custom role
Changes a custom role’s name, description or permissions. Requires roles:manage. The caller must hold every permission the role has, before and after. A change applies to every holder on their next request.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
role_id | string | yes |
Request body (application/json)
{ "name": "string", "description": "string", "permissions": [ "string" ]}Response 200 (application/json)
{ "role_id": "string", "name": "string", "description": "string", "permissions": [ "string" ], "builtin": true, "key_only": false}| Field | Type | Required | Description |
|---|---|---|---|
role_id | string | yes | What a membership, key, invitation or SCIM mapping stores: custom:<slug>, or a built-in role’s name. |
name | string | yes | |
description | string | null | no | |
permissions | string[] | yes | |
builtin | boolean | yes | A built-in role — listed for completeness, not editable. |
key_only | boolean | no | Only an API key can hold this role. |
403— The change would grant a permission the caller does not hold404— No such custom role; built-in roles cannot be changed
DELETE /v1/orgs/{org_id}/roles/{role_id}
Section titled “DELETE /v1/orgs/{org_id}/roles/{role_id}”Delete a custom role
Deletes a custom role. Requires roles:manage.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
role_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}403— Forbidden404— Not Found409— A member, an active API key, an open invitation or a SCIM group mapping still uses it; reassign those first
Named groups of an org’s members, such as “Platform” or “Security”. Teams grant no access: every member sees the same org-wide resources whatever their teams. A product can give teams a job, and a notification channel can be scoped to teams. A user can be on any number of teams. Admins manage teams; any member can view them.
team_id is a slug of name at creation and never changes. Names need not be unique: two teams named “Security” get security and security-2.
In this product a team owns repositories: their pull request reviews are routed to it.
GET /v1/orgs/{org_id}/teams
Section titled “GET /v1/orgs/{org_id}/teams”List teams for this org
The org’s teams. Any member.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "teams": [ { "team_id": "string", "org_id": "string", "name": "string", "created_by": "string", "created_at": "string", "updated_at": "string" } ]}POST /v1/orgs/{org_id}/teams
Section titled “POST /v1/orgs/{org_id}/teams”Create a team
Creates a team. Requires the org’s admin role. team_id is a slug of name, made unique in the org (security, security-2), and never changes afterwards.
In the dashboard: Organization → Access → Teams.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "name": "string"}Response 201 (application/json)
{ "team_id": "string", "org_id": "string", "name": "string", "created_by": "string", "created_at": "string", "updated_at": "string"}GET /v1/orgs/{org_id}/teams/{team_id}
Section titled “GET /v1/orgs/{org_id}/teams/{team_id}”Get one team
One team. Any member.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
team_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "team_id": "string", "org_id": "string", "name": "string", "created_by": "string", "created_at": "string", "updated_at": "string"}404— Team not found
PATCH /v1/orgs/{org_id}/teams/{team_id}
Section titled “PATCH /v1/orgs/{org_id}/teams/{team_id}”Rename a team
Renames a team. Requires the org’s admin role. team_id never changes, even when name does.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
team_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "name": "string"}Response 200 (application/json)
{ "team_id": "string", "org_id": "string", "name": "string", "created_by": "string", "created_at": "string", "updated_at": "string"}404— Not Found
DELETE /v1/orgs/{org_id}/teams/{team_id}
Section titled “DELETE /v1/orgs/{org_id}/teams/{team_id}”Delete a team
Deletes a team and every team_members row for it. Requires the org’s admin role. Unlike a rule category, which has an “Uncategorized” fallback, a team has nothing an orphaned membership could show under, so deletion cascades. Members keep their org membership.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
team_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Not Found
GET /v1/orgs/{org_id}/teams/{team_id}/members
Section titled “GET /v1/orgs/{org_id}/teams/{team_id}/members”List this team’s members
The team’s members (user_id, email, added_at). Any member.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
team_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "members": [ { "user_id": "string", "email": "string", "added_at": "string" } ]}404— Not Found
POST /v1/orgs/{org_id}/teams/{team_id}/members
Section titled “POST /v1/orgs/{org_id}/teams/{team_id}/members”Add an existing org member to this team
Adds an org member to the team. Requires the org’s admin role. user_id must already be a member of the org (GET /orgs/{org_id}/members).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
team_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "user_id": "string"}| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | yes | Must already be a member of this org (see GET /orgs/{org_id}/members) |
Response 201 (application/json)
{ "user_id": "string", "email": "string", "added_at": "string"}404— Team not found, oruser_idis not a member of this org409— The user is already on this team
DELETE /v1/orgs/{org_id}/teams/{team_id}/members/{user_id}
Section titled “DELETE /v1/orgs/{org_id}/teams/{team_id}/members/{user_id}”Remove a member from this team
Removes the user from this team only; their org membership stays. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
user_id | string | yes | |
team_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— The user is not on this team
Invitations
Section titled “Invitations”Reusable, expiring org-join links. The raw token is returned once and only its SHA-256 hash is stored. Unlike POST /orgs/{org_id}/members, the invitee needs no account yet: opening the link lets them register or log in and join. An invitation never grants owner.
An invitation created without an email is open: anyone holding the link can redeem it, and nobody can discover it. An invitation created with an email is addressed: only that account can redeem it (403 for anyone else), and it appears on that account’s GET /auth/me/invitations, which matters because this deployment sends no email.
GET /v1/invite/{token}
Section titled “GET /v1/invite/{token}”Preview an org invitation link — public, no auth
Public, no authentication. Lets an accept-invite page show “Join org as role” before the visitor logs in or registers. addressed says whether the invitation names one email, so the page can warn that any other account will be refused; it is a boolean, never the address, since the visitor has not proved who they are. Omits org_id on purpose.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes |
Response 200 (application/json)
{ "org_name": "string", "role": "string", "expires_at": "2026-01-01T00:00:00Z", "addressed": false}| Field | Type | Required | Description |
|---|---|---|---|
org_name | string | yes | |
role | string | yes | |
expires_at | string (date-time) | yes | |
addressed | boolean | no | Whether this invitation names a specific email address (InviteCreate.email), so the accept page can warn that signing in as anyone else will be refused. A bool, not the address itself: this endpoint is unauthenticated, and whoever holds the link has not proved they are the intended recipient. |
404— Token unknown, expired or revoked, on purpose indistinguishable
POST /v1/invite/{token}/accept
Section titled “POST /v1/invite/{token}/accept”Accept an org invitation link
Joins the invite’s org at its role. Requires a human session, not an API key. If the caller is already a member, nothing changes and their existing role comes back: accepting never raises or lowers a role. An invitation created with an email is addressed to that account: holding the link is not enough.
Accepting does not re-scope the session: the cookie still points at the previous org, or at no org. Follow it with POST /auth/session/switch on the returned org_id; the dashboard’s accept button does this.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes |
Response 200 (application/json) — Joined, or already a member with the role unchanged
{ "org_id": "8f2a...", "role": "member"}401— No session, or an API-key principal403— The invitation is addressed to another email404— Token unknown, expired or revoked
Search
Section titled “Search”Find records across the caller’s organization by name. A kind of record appears only for a caller who may list it, so a search never reaches past the caller’s access.
GET /v1/search
Section titled “GET /v1/search”Search the caller’s organization
Records of the caller’s organization whose name contains q, ignoring case: at most limit per kind, grouped by kind. Any role may call it.
Each kind needs the permission that guards its own list endpoint, such as teams:read for teams. A kind the caller cannot list is left out, never reported as forbidden, so a search shows what the caller could already open.
In the dashboard: the search bar at the top of every page.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
q | string | yes | Text to look for, two characters or more. |
limit | integer | no | Hits per kind. |
Response 200 (application/json)
{ "hits": [ { "kind": "string", "title": "string", "detail": "string", "ref": { "key": "string" } } ]}| Field | Type | Required | Description |
|---|---|---|---|
hits | SearchHit[] | yes | Grouped by kind, at most limit per kind. Only kinds the caller may list. |