# ロールの権限を設定

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

組織ロールの権限セットを置き換えます。組織ロールに対して環境が許可している権限のみ使用できます。また、管理者は自身が保持している権限のみを付与できます。権限や API はここでは作成できません。認証済みユーザーの `__Host-idp_session` Cookie が必要です。Cookie がない、期限切れ、または取り消されている場合は `401 unauthenticated` を返します。別オリジンのファーストパーティアプリは、代わりにフロント API アクセストークンを送信できます（`Authorization: DPoP <token>` と DPoP プルーフを付与します。詳細は [フロント API アクセストークン](/docs/api/fapi/front-api-token) を参照してください）。ユーザーは `idp_roles:manage` 権限を持つ組織のアクティブなメンバーである必要があります。メンバーでないユーザーには `404 not_found` を返し、組織の存在は開示されません。権限のないメンバーには `403 insufficient_permissions` を返します。組織ロールは環境で有効化され、そのプランに含まれている必要があります。

## リクエスト

ヘッダー:

| ヘッダー | 必須 | 説明 |
| --- | --- | --- |
| `Idp-Client` | はい | SDK 識別子。 |
| `Origin` | はい | 厳密に `https://<sign-in host>` である必要があります。 |
| `Content-Type` | ボディがある場合 | `application/json`。 |
| `If-Match` | いいえ | 最後に読み取ったロールの `"<version>"`。その後ロールが変更されていた場合は `412 precondition_failed` を返し、何も変更されません。 |

`org_id`: 組織の識別子（`org_…`）。`role_id`: ロールの識別子（`rol_…`）。

ボディ:

| フィールド | 必須 | 説明 |
| --- | --- | --- |
| `permission_ids` | はい | 権限の識別子（`perm_…`）の完全なセット。最大 100 件。`[]` を指定するとすべて削除されます。 |

## レスポンス

新しい `ETag` を含む `200 OK`。ボディはロールです（[組織ロールを取得](./get) を参照）。

## エラー

| ステータス | コード | 発生条件 |
| --- | --- | --- |
| 401 | `unauthenticated` | 有効なセッション Cookie がない。 |
| 403 | `origin_not_allowed` | `Origin` がない、または不正。 |
| 403 | `insufficient_permissions` | ユーザーが組織で `idp_roles:manage` を持っていない。 |
| 403 | `plan_feature_unavailable` | 環境のプランに組織ロールが含まれていない（`feature`、`required_plan`）。 |
| 403 | `org_custom_roles_disabled` | 環境で組織ロールが無効になっている。 |
| 403 | `role_not_assignable` | ロールまたは新しいセットが、ユーザーが保持していない権限を付与する、またはユーザー自身のメンバーシップがそのロールを持っている。 |
| 404 | `not_found` | このユーザーに対して該当する組織または組織ロールがない。環境ロール、存在しない、形式が不正、または他のユーザーの識別子も同じ応答になります。 |
| 409 | `organization_pending_deletion` | 組織が削除予定になっている。 |
| 412 | `precondition_failed` | `If-Match` が現在のバージョンを示していない、またはリクエストの処理中にロールが変更された。 |
| 422 | `permission_not_allowed` | 組織ロールに対してその権限は許可されていない。 |
| 422 | `permission_reserved` | 権限がプラットフォーム用に予約されている。 |
| 422 | `validation_failed` | リストが不正、または長すぎる。 |
| 503 | `service_unavailable` | 一時的に利用できない。`Retry-After` の後に再試行してください。 |

## 例

```bash
curl -X PUT https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w/permissions \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"permission_ids":["perm_01jbz6x8kq3m2n4p5r6s7t8v9b"]}'
```