# 組織ロールを取得

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

組織のロールを 1 件、または組織管理者が割り当てられる環境ロールを返します。認証済みユーザーの `__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 識別子。 |

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

ボディなし。

## レスポンス

`200 OK` と `ETag` ヘッダー（`"<version>"`）:

| フィールド | 型 | 説明 |
| --- | --- | --- |
| `id` | string | ロールの識別子（`rol_…`）。 |
| `organization_id` | string or null | 組織の識別子（`org_…`）。組織に割り当て可能な環境ロールの場合は `null`（ここでは読み取り専用）。 |
| `key` | string | ロールキー。組織および環境ロール内で一意であり、変更されません。 |
| `name` | string | 表示名。 |
| `description` | string | 説明。未設定の場合は空です。 |
| `is_privileged` | boolean | ロールが管理権限を付与するかどうか。 |
| `assignable_in_self_service` | boolean | 組織管理者がロールを割り当てられるかどうか。 |
| `permission_ids` | string[] | 権限の識別子（`perm_…`）。 |
| `created_at` | string | RFC 3339 形式（UTC）。 |
| `updated_at` | string | RFC 3339 形式（UTC）。 |
| `version` | integer | 現在のバージョン。`ETag` ヘッダー（`"<version>"`）としても送信されます。 |

```json
{
  "id": "rol_01jbz6x8kq3m2n4p5r6s7t8v9w",
  "organization_id": "org_01jbz6x8kq3m2n4p5r6s7t8v9a",
  "key": "auditor",
  "name": "Auditor",
  "description": "Read-only access to reports",
  "is_privileged": false,
  "assignable_in_self_service": true,
  "permission_ids": ["perm_01jbz6x8kq3m2n4p5r6s7t8v9b"],
  "created_at": "2026-10-28T09:30:00Z",
  "updated_at": "2026-10-28T09:30:00Z",
  "version": 1
}
```

## エラー

| ステータス | コード | 発生条件 |
| --- | --- | --- |
| 401 | `unauthenticated` | 有効なセッション Cookie がない。 |
| 403 | `insufficient_permissions` | ユーザーが組織で `idp_roles:manage` を持っていない。 |
| 403 | `plan_feature_unavailable` | 環境のプランに組織ロールが含まれていない（`feature`、`required_plan`）。 |
| 403 | `org_custom_roles_disabled` | 環境で組織ロールが無効になっている。 |
| 404 | `not_found` | このユーザーに対して該当する組織またはロールがない（存在しない、形式が不正、または他のユーザーの識別子も同じ応答になります）。 |
| 503 | `service_unavailable` | 一時的に利用できない。`Retry-After` の後に再試行してください。 |

## 例

```bash
curl https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -b cookies.txt
```