List the custom roles of an organization

GET /v1/organizations/{org_id}/roles · permission roles:read

Lists the organization's custom roles, oldest first. Only forward pagination is supported: before and an order other than asc return 422. The cursor is bound to this list. Organization roles are visible only in their organization and are not part of the environment list. The role's permission set is not returned in this release.

Request

Field	Type	Required	Description
`org_id`	path	yes	Organization ID (`org_…`).
`limit`	query	no	1–100, default 20.
`after`	query	no	Cursor from `list_metadata.after`.

No request body.

Response

200 OK with a page of roles.

{
  "data": [
    {
      "id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
      "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "key": "billing-admin",
      "name": "Billing admin",
      "description": "",
      "is_privileged": false,
      "assignable_in_self_service": true,
      "permission_ids": [],
      "created_at": "2026-10-12T09:31:00.123456Z",
      "updated_at": "2026-10-12T09:31:00.123456Z",
      "version": 1
    }
  ],
  "list_metadata": {
    "before": null,
    "after": null
  }
}

Errors

HTTP	code	When
400	`invalid_cursor`	The cursor is invalid or belongs to another list.
404	`not_found`	The organization does not exist in this environment.
422	`validation_failed`	`limit` is out of range, or `before` or a non-`asc` `order` was given.
401	`unauthenticated`	The credential is missing, invalid or revoked.
403	`insufficient_permissions`	The credential lacks the required permission.
429	`rate_limited`	The rate limit was exceeded; retry after the `Retry-After` period.
503	`service_unavailable`	A dependency is temporarily unavailable; retry after the `Retry-After` period.

Example

curl -i "https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/roles?limit=20" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"