Members
Organization membership, roles (Owner/Admin/User), and per-environment access grants for User-role members.
7 endpoints
Lists an organization's members, paginated. Requires only membership, not a minimum role — seeing who's on the team isn't a privileged action.
get/v1/organizations/{organization_id}/membersRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| organization_id* | path | string<uuid> | Organization id |
| page | query | integer<int32> | 1-indexed page number. Defaults to 1. |
| per_page | query | integer<int32> | Members per page, capped at 100. Defaults to 20. |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | ListMembersResponse | A page of the organization's members |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 404 | ErrorBody | No organization with this id exists, or the caller is not a member of it |
Adds a user to the organization with the given role. Requires the caller to be an Owner or Admin.
post/v1/organizations/{organization_id}/membersRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| organization_id* | path | string<uuid> | Organization id |
Request bodyAddMemberRequest
| Field | Type | Description |
|---|---|---|
| role* | string | "admin" or "user" — "owner" is rejected. Every organization
gets exactly one Owner, assigned at creation
(organizations::create::create_organization); there is no membership
transfer operation yet to reassign it. |
| user_id* | string | — |
Responses
| Status | Body | Description |
|---|---|---|
| 201 | MemberSummary | The newly created membership |
| 400 | ErrorBody | role is not "admin" or "user" |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but not an Owner or Admin |
| 404 | ErrorBody | No organization with this id exists, or the caller is not a member of it |
| 409 | ErrorBody | This user is already a member of the organization |
Changes a member's role to Admin or User. Never accepts `"owner"` — see [`db::organization_members::update_role`], there is no membership transfer operation yet.
patch/v1/organizations/{organization_id}/members/{member_id}Requires a bearer token
Requires the caller to be an Owner or Admin — and if the caller is
only an Admin, the target member must currently have the User role:
per docs/architecture/tenancy.md's permission table, an Admin cannot
touch the Owner's or another Admin's role, only the Owner can.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| organization_id* | path | string<uuid> | Organization id |
| member_id* | path | string<uuid> | Membership id |
Request bodyUpdateMemberRoleRequest
| Field | Type | Description |
|---|---|---|
| role* | string | — |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | MemberSummary | The updated membership |
| 400 | ErrorBody | role is not "admin" or "user" |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but not an Owner or Admin, or is an Admin trying to change the Owner's or another Admin's role |
| 404 | ErrorBody | No organization or membership with this id exists, or the caller is not a member of the organization |
| 409 | ErrorBody | The target membership is the organization's Owner, or role is "owner" |
Removes a member from the organization. The Owner can never be removed this way (see [`db::organization_members::remove_member`]).
delete/v1/organizations/{organization_id}/members/{member_id}Requires a bearer token
Requires the caller to be an Owner or Admin, with the same
Admin-cannot-touch-Owner-or-another-Admin restriction as
[crate::members::update_role::update_member_role].
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| organization_id* | path | string<uuid> | Organization id |
| member_id* | path | string<uuid> | Membership id |
Responses
| Status | Body | Description |
|---|---|---|
| 204 | — | The member was removed |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but not an Owner or Admin, or is an Admin trying to remove the Owner or another Admin |
| 404 | ErrorBody | No organization or membership with this id exists, or the caller is not a member of the organization |
| 409 | ErrorBody | The target membership is the organization's Owner |
Lists a member's granted environment access.
get/v1/organizations/{organization_id}/members/{member_id}/environment-accessRequires a bearer token
Requires the caller to be an Owner or Admin — like granting/revoking,
this is an org-management action per docs/architecture/tenancy.md's
permission table, not something a User-role member can inspect about
themselves through this endpoint.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| organization_id* | path | string<uuid> | Organization id |
| member_id* | path | string<uuid> | Membership id |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | — | The member's granted environment access |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but not an Owner or Admin |
| 404 | ErrorBody | No organization or membership with this id exists, or the caller is not a member of the organization |
Grants a member access to one of the organization's environments.
post/v1/organizations/{organization_id}/members/{member_id}/environment-accessRequires a bearer token
Only meaningful for User-role members — Owners and Admins already
implicitly access every environment in the org (see
[db::organization_members::grant_environment_access]), so
granting access to an Owner or Admin membership is rejected rather than
silently accepted and ignored. Requires the caller to be an Owner or
Admin.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| organization_id* | path | string<uuid> | Organization id |
| member_id* | path | string<uuid> | Membership id |
Request bodyGrantEnvironmentAccessRequest
| Field | Type | Description |
|---|---|---|
| environment_id* | string<uuid> | — |
Responses
| Status | Body | Description |
|---|---|---|
| 201 | EnvironmentAccessSummary | The newly created grant |
| 400 | ErrorBody | The target membership does not have the User role |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but not an Owner or Admin |
| 404 | ErrorBody | No organization, membership, or environment with this id exists, or the caller is not a member of the organization |
| 409 | ErrorBody | This member already has access to this environment |
Revokes a member's access to an environment. Idempotent.
delete/v1/organizations/{organization_id}/members/{member_id}/environment-access/{environment_id}Requires a bearer token
Revoking access that was never granted, or already revoked, still
returns 204 (see
[db::organization_members::revoke_environment_access]).
Requires the caller to be an Owner or Admin.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| organization_id* | path | string<uuid> | Organization id |
| member_id* | path | string<uuid> | Membership id |
| environment_id* | path | string<uuid> | Environment id |
Responses
| Status | Body | Description |
|---|---|---|
| 204 | — | The grant was revoked, or never existed |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but not an Owner or Admin |
| 404 | ErrorBody | No organization or membership with this id exists, or the caller is not a member of the organization |