組織ロールを取得
GET /fapi/v1/organizations/{org_id}/roles/{role_id} · 環境のサインインホストから呼び出し
組織のロールを 1 件、または組織管理者が割り当てられる環境ロールを返します。認証済みユーザーの __Host-idp_session Cookie が必要です。Cookie がない、期限切れ、または取り消されている場合は 401 unauthenticated を返します。別オリジンのファーストパーティアプリは、代わりにフロント API アクセストークンを送信できます（Authorization: DPoP <token> と DPoP プルーフを付与します。詳細は フロント API アクセストークン を参照してください）。ユーザーは 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>"）としても送信されます。 |
{
"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 の後に再試行してください。 |
例
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