# 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.

```json
{
  "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

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