# 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](/docs/api/fapi/front-api-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](/docs/api/fapi/organizations/memberships/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

```bash
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"]}'
```

```json
{
  "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](/docs/policies/personal-data) 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.