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). 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>"). 
{
  "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

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