# Get an organization role

`GET /fapi/v1/organizations/{org_id}/roles/{role_id}` · called from the environment's sign-in host

Returns one role of the organization, or an environment role that organization administrators may assign. Requires the authenticated user's `__Host-idp_session` cookie; if the cookie is missing, expired, or revoked, returns `401 unauthenticated`. A first-party app on another origin can instead send its front API access token (`Authorization: DPoP <token>` with a DPoP proof; see [Front API access token](/docs/api/fapi/front-api-token)). The user must be an active member of the organization with the `idp_roles:manage` permission. A user who is not a member gets `404 not_found`, so the organization's existence is not disclosed; a member without the permission gets `403 insufficient_permissions`. Organization roles must be enabled for the environment and included in its plan.

## Request

Headers:

| Header | Required | Description |
| --- | --- | --- |
| `Idp-Client` | yes | SDK identifier. |

`org_id`: the organization identifier (`org_…`). `role_id`: the role identifier (`rol_…`).

No body.

## Response

`200 OK` with an `ETag` header (`"<version>"`):

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Role identifier (`rol_…`). |
| `organization_id` | string or null | Organization identifier (`org_…`); `null` for an environment role offered for assignment in the organization (read only here). |
| `key` | string | Role key; unique in the organization and among environment roles; never changes. |
| `name` | string | Display name. |
| `description` | string | Description; empty when not set. |
| `is_privileged` | boolean | Whether the role grants administrative permissions. |
| `assignable_in_self_service` | boolean | Whether organization administrators may assign the role. |
| `permission_ids` | string[] | Permission identifiers (`perm_…`). |
| `created_at` | string | RFC 3339, UTC. |
| `updated_at` | string | RFC 3339, UTC. |
| `version` | integer | Current version; also sent as the `ETag` header (`"<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
}
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | No valid session cookie. |
| 403 | `insufficient_permissions` | The user lacks `idp_roles:manage` in the organization. |
| 403 | `plan_feature_unavailable` | The environment's plan does not include organization roles (`feature`, `required_plan`). |
| 403 | `org_custom_roles_disabled` | Organization roles are turned off for the environment. |
| 404 | `not_found` | No such organization or role for this user (an unknown, malformed or foreign identifier answers the same). |
| 503 | `service_unavailable` | Temporarily unavailable; retry after `Retry-After`. |

## Example

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