Skip to content
DashboardWebsite

Endpoints: Organizations, Teams & Invitations

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.

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 organization info

One organization’s info. Requires membership in it.

Path parameters

NameTypeRequiredDescription
org_idstringyes

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 to org_id
  • 404 — Organization not found

List organization members

Every member of the org. Any role may call it.

  • name is null until the user sets one with PATCH /auth/me.
  • is_active is org-scoped: false means the account is deactivated in this org only (see PATCH /orgs/{org_id}/members/{user_id}).
  • account_active is the whole account’s User.is_active. Only a platform admin changes it (PATCH /admin/users/{user_id}); false blocks login in every org.
  • teams lists the teams the member is on, from team_members; any number, or none.

In the dashboard: Organization → Access → Members.

Path parameters

NameTypeRequiredDescription
org_idstringyes

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"
}
]
}

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"email": "[email protected]",
"role": "member"
}

Response 201 (application/json) — Member added

{
"user_id": "u2...",
"org_id": "8f2a...",
"role": "member"
}
  • 200
  • 403 — Forbidden
  • 404 — No registered user with that email
  • 409 — The user is already a member of this org

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

NameTypeRequiredDescription
org_idstringyes
user_idstringyes

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"
}
FieldTypeRequiredDescription
user_idstringyes
emailstringyes
namestring | nullno
rolestringyes
is_activebooleannoOrg-scoped — see Membership.is_active. Distinct from account_active.
account_activebooleannoAccount-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_atstring (date-time)yes
teamsstring[]noNames 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" | nullnoSee Membership.provisioned_via.
  • 400 — Targets the caller’s own membership
  • 403 — Forbidden
  • 404 — user_id is not a member of this org
  • 409 — 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

NameTypeRequiredDescription
org_idstringyes
user_idstringyes
  • 200
  • 204 — No Content
  • 400 — Targets the caller’s own membership
  • 403 — Forbidden
  • 404 — user_id is not a member of this org
  • 409 — The target is the org’s only remaining owner

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json, optional)

{
"hand_over": {
"key": "string"
},
"lock": [
"string"
]
}
FieldTypeRequiredDescription
hand_overobjectnoorg_id → user_id of the active member who becomes that organization’s owner.
lockstring[]noorg_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 org
  • 404 — org_id is not the caller’s current org
  • 409 — The caller is the org’s only owner and sent neither hand_over nor lock for 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

NameTypeRequiredDescription
org_idstringyes
user_idstringyes

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 SSO
  • 403 — Forbidden
  • 404 — user_id is 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

NameTypeRequiredDescription
org_idstringyes
user_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 403 — Forbidden
  • 404 — user_id is not a member of this org

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

NameTypeRequiredDescription
org_idstringyes

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
}
]
}

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"role": "member",
"email": "[email protected]"
}
FieldTypeRequiredDescription
rolestringno
emailstring (email) | nullnoAddress 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

NameTypeRequiredDescription
org_idstringyes
invite_idstringyes
  • 200
  • 204 — No Content
  • 403 — Forbidden
  • 404 — Invite not found

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

NameTypeRequiredDescription
org_idstringyes

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 — Unauthorized
  • 403 — 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.

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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"roles": [
{
"role_id": "string",
"name": "string",
"description": "string",
"permissions": [
"string"
],
"builtin": true,
"key_only": false
}
]
}

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"name": "string",
"description": "string",
"permissions": [
"string"
]
}
FieldTypeRequiredDescription
namestringyes
descriptionstring | nullno
permissionsstring[]yesDeclared permission names (GET /permissions).

Response 201 (application/json)

{
"role_id": "string",
"name": "string",
"description": "string",
"permissions": [
"string"
],
"builtin": true,
"key_only": false
}
FieldTypeRequiredDescription
role_idstringyesWhat a membership, key, invitation or SCIM mapping stores: custom:<slug>, or a built-in role’s name.
namestringyes
descriptionstring | nullno
permissionsstring[]yes
builtinbooleanyesA built-in role — listed for completeness, not editable.
key_onlybooleannoOnly an API key can hold this role.
  • 403 — The role would grant a permission the caller does not hold

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

NameTypeRequiredDescription
org_idstringyes
role_idstringyes

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
}
FieldTypeRequiredDescription
role_idstringyesWhat a membership, key, invitation or SCIM mapping stores: custom:<slug>, or a built-in role’s name.
namestringyes
descriptionstring | nullno
permissionsstring[]yes
builtinbooleanyesA built-in role — listed for completeness, not editable.
key_onlybooleannoOnly an API key can hold this role.
  • 403 — The change would grant a permission the caller does not hold
  • 404 — No such custom role; built-in roles cannot be changed

Delete a custom role

Deletes a custom role. Requires roles:manage.

Path parameters

NameTypeRequiredDescription
org_idstringyes
role_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 403 — Forbidden
  • 404 — Not Found
  • 409 — 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.

List teams for this org

The org’s teams. Any member.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"teams": [
{
"team_id": "string",
"org_id": "string",
"name": "string",
"created_by": "string",
"created_at": "string",
"updated_at": "string"
}
]
}

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

NameTypeRequiredDescription
org_idstringyes

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 one team

One team. Any member.

Path parameters

NameTypeRequiredDescription
team_idstringyes
org_idstringyes

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

Rename a team

Renames a team. Requires the org’s admin role. team_id never changes, even when name does.

Path parameters

NameTypeRequiredDescription
team_idstringyes
org_idstringyes

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 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

NameTypeRequiredDescription
team_idstringyes
org_idstringyes

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

NameTypeRequiredDescription
team_idstringyes
org_idstringyes

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

NameTypeRequiredDescription
team_idstringyes
org_idstringyes

Request body (application/json)

{
"user_id": "string"
}
FieldTypeRequiredDescription
user_idstringyesMust 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, or user_id is not a member of this org
  • 409 — 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

NameTypeRequiredDescription
user_idstringyes
team_idstringyes
org_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 404 — The user is not on this team

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.

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

NameTypeRequiredDescription
tokenstringyes

Response 200 (application/json)

{
"org_name": "string",
"role": "string",
"expires_at": "2026-01-01T00:00:00Z",
"addressed": false
}
FieldTypeRequiredDescription
org_namestringyes
rolestringyes
expires_atstring (date-time)yes
addressedbooleannoWhether 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

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

NameTypeRequiredDescription
tokenstringyes

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 principal
  • 403 — The invitation is addressed to another email
  • 404 — Token unknown, expired or revoked

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.

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

NameTypeRequiredDescription
qstringyesText to look for, two characters or more.
limitintegernoHits per kind.

Response 200 (application/json)

{
"hits": [
{
"kind": "string",
"title": "string",
"detail": "string",
"ref": {
"key": "string"
}
}
]
}
FieldTypeRequiredDescription
hitsSearchHit[]yesGrouped by kind, at most limit per kind. Only kinds the caller may list.