Set a member's roles

PUT /fapi/v1/organizations/{org_id}/memberships/{membership_id}/roles · called from the environment's sign-in host

Replaces the roles of a membership with a full set, for an organization profile screen. The set covers only the roles you can see in this organization: its own roles and the environment roles open to organization admins. The member's other roles stay. An empty set removes all the roles you can see; if the member is left with none, the organization's default role is assigned.

Requires the authenticated user's __Host-idp_session cookie with an exact Origin, or a first-party app's front API access token (Authorization: DPoP <token> with a DPoP proof; see Front API access token). The user must be an active member of the organization with the idp_members:update_roles permission. A user who is not a member gets 404 not_found; a member without the permission gets 403 insufficient_permissions.

Assignment rules:

Every permission of each role you assign must be one you hold yourself.
Only a member who holds the admin role can assign a privileged role.
You cannot change your own roles.
The last active admin cannot lose the admin role (409 last_org_admin).

With @keenauth/js: await keenauth.organizations.setMemberRoles(orgId, membershipId, [roleId], { expectedVersion: 3 }).

Request

Headers:

Header	Required	Description
`Idp-Client`	yes	SDK identifier.
`Origin`	yes, with the cookie	`https://<sign-in host>`.
`If-Match`	no	One version, `"<version>"`, from the member list. A version that does not match, or more than one version, returns `412 precondition_failed`.

org_id: the organization identifier (org_…). membership_id: the membership identifier (mem_…).

Body: {"role_ids": ["rol_…"]}, at most 50 roles. role_ids is required; [] is a valid set.

Response

200 OK with the membership (the same fields as an item of the member list) and ETag: "<version>".

Errors

Status	Code	When
400	`malformed_request`	`If-Match` is malformed.
400	`unknown_field`	The body has a field other than `role_ids`.
401	`unauthenticated`	No valid session cookie or token.
403	`insufficient_permissions`	The user lacks `idp_members:update_roles` in the organization.
403	`role_not_assignable`	An assignment rule above refuses the change.
403	`origin_not_allowed`	The `Origin` does not match.
404	`not_found`	No such organization, membership or role for this user; an unknown, malformed or foreign identifier answers the same.
409	`last_org_admin`	The change would leave the organization without an active admin.
409	`role_limit_reached`	The member would hold more than 50 roles.
409	`organization_disabled`	The organization is disabled or pending deletion (`organization_pending_deletion`).
412	`precondition_failed`	`If-Match` does not name the membership's current version.
422	`validation_failed`	`role_ids` is missing, too long, or holds a malformed identifier.
503	`service_unavailable`	Temporarily unavailable; retry after `Retry-After`.

Example

curl -X PUT "https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/memberships/mem_01jbz6x8kq3m2n4p5r6s7t8v9b/roles" \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "3"' \
  -b cookies.txt \
  -d '{"role_ids":["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"]}'

{
  "id": "mem_01jbz6x8kq3m2n4p5r6s7t8v9b",
  "user_id": "usr_01jbz6x8kq3m2n4p5r6s7t8v9c",
  "status": "active",
  "roles": [{ "role_id": "rol_01jbz6x8kq3m2n4p5r6s7t8v9w", "source": "admin_api" }],
  "created_at": "2026-11-03T09:00:00Z",
  "activated_at": "2026-11-03T09:00:00Z",
  "expires_at": null,
  "updated_at": "2026-11-03T10:00:00Z",
  "version": 4
}

Personal data

This endpoint carries personal data: organization memberships and invitations. Personal data in the KeenAuth APIs describes what is stored, how long it is kept and how it is deleted. Do not send special categories of personal data (health, biometric data, religion, political opinions, sexual orientation) in any field.