List organization roles

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

Returns the organization's own roles and the environment roles that organization administrators may assign, ordered by identifier. 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_…).

Query parameters:

Parameter	Required	Description
`limit`	no	Page size, 1 to 100; default 20.
`after`	no	The `next_after` value of the previous page.

No body.

Response

200 OK:

Field	Type	Description
`data[]`	object[]	Roles, with the fields described in Get an organization role.
`next_after`	string	Pass as `after` for the next page; absent on the last page.

{
  "data": [
    {
      "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
400	`invalid_cursor`	`after` is not a role identifier from a previous page.
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).
422	`validation_failed`	`limit` is out of range.
503	`service_unavailable`	Temporarily unavailable; retry after `Retry-After`.

Example

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