List Roles

Returns your organization’s roles, one page at a time.

A role is a named bundle of permissions. It is what you grant to a group (or, less commonly, straight to a person); the permissions inside it are what the holder may then do. Called whenever the role list is shown, and after any create or delete to refresh it.

The filters are relational, not text matching: userId narrows to the roles that user holds and groupId to the roles granted to that group, which is how you answer “what does this person have?” without walking every role. name is the substring match.

Read-only: nothing changes.

Failures:

• 400 IDE-0018 — limit is above the deployment’s maximum (100 by default).
• 400 IDE-0019 — page is below 1.
• 503 IDE-0066 — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.

GET /v1/roles

List Roles

cURL

curl --request GET \
  --url https://identity.sandbox.lerian.net/v1/roles \
  --header 'Authorization: Bearer <token>'

200

{
  "items": [
    {
      "createdAt": "2026-06-24T10:00:00Z",
      "description": "A custom editor role",
      "groups": [
        "<string>"
      ],
      "id": "custom-editor",
      "isEnabled": true,
      "isSystem": false,
      "name": "Custom Editor",
      "roles": [
        "<string>"
      ],
      "users": [
        "<string>"
      ]
    }
  ],
  "limit": 10,
  "page": 1,
  "total": 10
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Query Parameters

page · integer<int64> · default: 1

Page number.

Example:

1

limit · integer<int64> · default: 10

Items per page.

Example:

10

name · string

Filter by name (case-insensitive substring).

userId · string

Filter by user ID (relational listing): only roles the user holds.

groupId · string

Filter by group ID (relational listing): only roles granted to the group.

Response

200

application/json

OK

items · object[]

The page of roles.

Show child attributes

limit · integer<int64>

The page size that was applied.

Example:

10

page · integer<int64>

The 1-based page this response corresponds to.

Example:

1

total · integer<int64>

Total number of roles, across all pages.

Example:

10