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, paginated
`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 answers 201 with 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	400 with the reason `already_exists`. Duplicate membership is rejected
User is in a different realm than the organization	400 with the reason `invalid`
Organization is disabled (`enabled: false`)	400 with the reason `invalid`
User id that does not exist	404
Removing a user who is not a member	404

Listing members

GET /realms/{realm_name}/organizations/{organization_id}/members

The list is paginated, as described in API listings, and answers { data, metadata }. Each entry in data is a membership record, the same shape you get back when adding a member: id, organization_id, user_id and created_at, the date the user joined. It carries no username or email. Resolve the user_id against the users API when you need to show a name.

The filters apply to the member’s user:

Parameter	Matches
`search`	Case-insensitive substring of the username or the email
`username`, `email`	Case-insensitive substring of that field
`enabled`	Whether the user account is enabled, `true` or `false`
`created_from`, `created_to`	The membership date, as RFC 3339 date-times, inclusive and exclusive

order_by accepts username, email and created_at (the default, which is the membership date).

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 a plain array of membership records, each with id, organization_id, user_id and created_at. It is not paginated, and it is 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 and answers 204. If the user is not a member, the call answers 404. 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.

Permissions

Listing members, member roles and a user’s organizations needs view_organizations, manage_organizations or manage_realm. Adding and removing members, and assigning or revoking roles, needs manage_organizations or manage_realm. manage_users is not enough.

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.