# 組織ロールを作成

`POST /fapi/v1/organizations/{org_id}/roles` · 環境のサインインホストから呼び出されます

権限を含まないロールを組織内に作成します。権限は [ロールの権限を設定](./set-permissions) で追加します。1 つの組織に作成できるロールは最大 50 件です。認証済みユーザーの `__Host-idp_session` Cookie が必要です。Cookie がない、期限切れ、または取り消されている場合は `401 unauthenticated` が返されます。別のオリジンの First-party アプリは、代わりに Front API アクセストークン（DPoP 証明付きの `Authorization: DPoP <token>`。[Front 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`。 |

`org_id`: 組織の識別子（`org_…`）。

ボディ:

| フィールド | 必須 | 説明 |
| --- | --- | --- |
| `key` | はい | ロールのキー。組織内および環境ロールの中で一意である必要があり、後から変更できません。 |
| `name` | はい | 表示名。 |
| `description` | いいえ | 説明。 |

## レスポンス

`201 Created` と `Location` および `ETag` ヘッダーが返されます。ボディはロールです（[組織ロールを取得](./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` | 環境で組織ロールがオフになっています。 |
| 404 | `not_found` | このユーザーに対応する組織またはロールがありません。未知、形式不正、または他の組織の識別子も同じ応答になります。 |
| 409 | `role_key_conflict` | そのキーは組織内、または環境ロールで既に使用されています。 |
| 409 | `role_limit_reached` | 組織にすでに 50 件のロールがあります。 |
| 409 | `organization_pending_deletion` | 組織は削除予定です。 |
| 422 | `validation_failed` | フィールドがないか不正です。`errors[]` にフィールド名が示されます。 |
| 503 | `service_unavailable` | 一時的に利用できません。`Retry-After` の後に再試行してください。 |

## 例

```bash
curl -X POST https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles \
  -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 '{"key":"auditor","name":"Auditor"}'
```