Members

Membership connects a user to an organization. A user can belong to several organizations in the same realm, and an organization takes any number of members. Roles can then be assigned to a member within that organization, or inherited from a group.

Membership endpoints

Method	Endpoint	Description
`GET`	`/realms/{realm_name}/organizations/{organization_id}/members`	List the members of an organization
`POST`	`/realms/{realm_name}/organizations/{organization_id}/members`	Add a user to an organization
`DELETE`	`/realms/{realm_name}/organizations/{organization_id}/members/{user_id}`	Remove a user from an organization
`GET`	`/realms/{realm_name}/users/{user_id}/organizations`	List the organizations a user belongs to

Adding a member

Send the target user_id in the request body:

{
  "user_id": "01936b2e-5678-7000-abcd-000000000002"
}

A successful addition returns the new membership record:

{
  "id": "01936b2e-9999-7000-abcd-000000000003",
  "organization_id": "01936b2e-1234-7000-abcd-000000000001",
  "user_id": "01936b2e-5678-7000-abcd-000000000002",
  "created_at": "2026-06-16T10:00:00Z"
}

Adding a member step by step

Confirm the organization is enabled

A disabled organization (enabled: false) rejects new member additions. Check the organization’s enabled field before attempting to add members. Re-enable it with a PUT to the organization endpoint if needed.

Confirm the user is in the same realm

The user must belong to the same realm as the organization. Cross-realm membership is rejected. Verify realm_id on the organization matches the realm the user was created in.

POST to the members endpoint

Send { "user_id": "<uuid>" } to POST /realms/{realm_name}/organizations/{organization_id}/members. The user is added immediately.

Verify with a list call

Confirm the user appears in GET /realms/{realm_name}/organizations/{organization_id}/members or in GET /realms/{realm_name}/users/{user_id}/organizations.

Behavior rules

Situation	Result
User already a member of this organization	`AlreadyExists`. Duplicate membership is rejected
User is in a different realm than the organization	Request rejected
Organization is disabled (`enabled: false`)	Request rejected
Removing a user who is not a member	`NotFound`

Listing a user’s organizations

To find every organization a user belongs to within the realm:

GET /realms/{realm_name}/users/{user_id}/organizations

The response is an array of membership records, each with organization_id, user_id, and created_at. That is the same OrganizationMember shape you get back when adding a member, not a full organization object, so resolve each organization_id against GET /realms/{realm_name}/organizations/{organization_id} when you need the details. It is what a workspace switcher is built on.

Removing a member

DELETE /realms/{realm_name}/organizations/{organization_id}/members/{user_id}

Removal takes effect immediately. If the user is not a member, the call returns NotFound. Nothing cascades to the user’s account: the user record is untouched.

Member roles

A membership record itself has no role field. Roles are attached to the member through a separate set of endpoints, scoped to the organization.

Method	Endpoint	Description
`GET`	`/realms/{realm_name}/organizations/{organization_id}/members/{user_id}/roles`	List the roles the member holds in this organization
`POST`	`/realms/{realm_name}/organizations/{organization_id}/members/{user_id}/roles`	Assign a role to the member
`DELETE`	`/realms/{realm_name}/organizations/{organization_id}/members/{user_id}/roles/{role_id}`	Revoke a role from the member

Assignment takes the role id in the body and answers 204 No Content:

{
  "role_id": "01936b2e-7777-7000-abcd-000000000004"
}

GET returns the full role objects, so a client can read their names and permissions without a second lookup.

Roles can also come from a group

Groups inside an organization carry role mappings of their own, and membership in a group is recursive: a member of a group effectively belongs to all of its ancestors, and inherits their roles. See Groups.