# メンバーのロールを設定する

`PUT /fapi/v1/organizations/{org_id}/memberships/{membership_id}/roles` · 環境のサインインホストから呼び出します

組織のプロフィール画面で使用するため、メンバーシップのロールを完全なセットで置き換えます。このセットに含まれるのは、この組織で見えるロール、つまりこの組織のロールと、組織管理者が利用できる環境のロールのみです。メンバーの他のロールは維持されます。空のセットを指定すると、見えるロールがすべて削除されます。メンバーにロールが残らない場合は、組織のデフォルトロールが割り当てられます。

認証済みユーザーの `__Host-idp_session` Cookie と完全一致する `Origin`、またはファーストパーティアプリのフロント API アクセストークン（DPoP 証明付きの `Authorization: DPoP <token>`。[フロント API アクセストークン](/docs/api/fapi/front-api-token)を参照してください）が必要です。ユーザーは、`idp_members:update_roles` 権限を持つ組織のアクティブなメンバーである必要があります。メンバーではないユーザーには `404 not_found` が返されます。権限のないメンバーには `403 insufficient_permissions` が返されます。

割り当てのルール:

- 割り当てる各ロールのすべての権限は、ご自身が保有している必要があります。
- 特権ロールを割り当てられるのは、管理者ロールを持つメンバーのみです。
- ご自身のロールは変更できません。
- 最後のアクティブな管理者から管理者ロールを外すことはできません（`409 last_org_admin`）。

`@keenauth/js` を使用する場合: `await keenauth.organizations.setMemberRoles(orgId, membershipId, [roleId], { expectedVersion: 3 })`

## リクエスト

ヘッダー:

| ヘッダー | 必須 | 説明 |
| --- | --- | --- |
| `Idp-Client` | はい | SDK 識別子です。 |
| `Origin` | Cookie を使用する場合は必須 | `https://<サインインホスト>`。 |
| `If-Match` | いいえ | メンバー一覧から取得した 1 つのバージョン `"<version>"`。一致しないバージョン、または複数のバージョンを指定すると `412 precondition_failed` が返されます。 |

`org_id`: 組織の識別子（`org_…`）です。`membership_id`: メンバーシップの識別子（`mem_…`）です。

ボディ: `{"role_ids": ["rol_…"]}`。最大 50 件のロールを指定できます。`role_ids` は必須です。`[]` は有効なセットです。

## レスポンス

`200 OK` とメンバーシップ（[メンバー一覧](/docs/api/fapi/organizations/memberships/list)の項目と同じフィールド）、および `ETag: "<version>"` が返されます。

## エラー

| ステータス | コード | 発生条件 |
| --- | --- | --- |
| 400 | `malformed_request` | `If-Match` の形式が正しくありません。 |
| 400 | `unknown_field` | ボディに `role_ids` 以外のフィールドが含まれています。 |
| 401 | `unauthenticated` | 有効なセッション Cookie またはトークンがありません。 |
| 403 | `insufficient_permissions` | ユーザーに組織内の `idp_members:update_roles` 権限がありません。 |
| 403 | `role_not_assignable` | 上記の割り当てルールにより、この変更は拒否されます。 |
| 403 | `origin_not_allowed` | `Origin` が一致しません。 |
| 404 | `not_found` | このユーザーに対して、該当する組織、メンバーシップ、またはロールが存在しません。存在しない識別子、形式が不正な識別子、他の組織の識別子はいずれも同じ応答になります。 |
| 409 | `last_org_admin` | 変更すると、組織にアクティブな管理者がいなくなります。 |
| 409 | `role_limit_reached` | メンバーが 50 件を超えるロールを保持することになります。 |
| 409 | `organization_disabled` | 組織が無効化されているか、削除保留中です（`organization_pending_deletion`）。 |
| 412 | `precondition_failed` | `If-Match` がメンバーシップの現在のバージョンを指定していません。 |
| 422 | `validation_failed` | `role_ids` が欠けているか、長すぎるか、または形式の不正な識別子を含んでいます。 |
| 503 | `service_unavailable` | 一時的に利用できません。`Retry-After` の後に再試行してください。 |

## 例

```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
}
```

## 個人データ

このエンドポイントは個人データ（組織のメンバーシップと招待）を扱います。[KeenAuth API における個人データ](/docs/policies/personal-data)では、保存される内容、保存期間、削除方法について説明しています。いずれのフィールドにも、特別な種類の個人データ（健康、生体情報、宗教、政治的意見、性的指向）を送信しないでください。