Get roles

GET /api/roles
OAuth2

Get roles with filters and pagination.

Query parameters

  • excludeUserId string

    Exclude roles assigned to a user.

  • excludeApplicationId string

    Exclude roles assigned to an application.

  • type string

    Filter by role type.

    Values are User or MachineToMachine.

  • page integer

    Page number (starts from 1).

    Minimum value is 1. Default value is 1.

  • page_size integer

    Entries per page.

    Minimum value is 1. Default value is 20.

  • search_params object

    Search query parameters.

    Hide search_params attribute Show search_params attribute object
    • * string Additional properties

Responses

  • 200 application/json

    An array of roles matching the filters.

    Hide response attributes Show response attributes object
    • tenantId string Required

      Maximum length is 21.

    • id string Required

      Minimum length is 1, maximum length is 21.

    • name string Required

      Minimum length is 1, maximum length is 128.

    • description string Required

      Minimum length is 1, maximum length is 128.

    • type string Required

      Values are User or MachineToMachine.

    • isDefault boolean Required
    • usersCount number Required
    • featuredUsers array[object] Required
      Hide featuredUsers attributes Show featuredUsers attributes object
      • id string Required

        Minimum length is 1, maximum length is 12.

      • avatar string | null Required

        Maximum length is 2048.

      • name string | null Required

        Maximum length is 128.

    • applicationsCount number Required
    • featuredApplications array[object] Required
      Hide featuredApplications attributes Show featuredApplications attributes object
      • id string Required

        Minimum length is 1, maximum length is 21.

      • name string Required

        Minimum length is 1, maximum length is 256.

      • type string Required

        Values are Native, SPA, Traditional, MachineToMachine, Protected, or SAML.
  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

GET /api/roles 
curl \
 -X GET https://[tenant_id].logto.app/api/roles \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
[
  {
    "tenantId": "string",
    "id": "string",
    "name": "string",
    "description": "string",
    "type": "User",
    "isDefault": true,
    "usersCount": 42.0,
    "featuredUsers": [
      {
        "id": "string",
        "avatar": "string",
        "name": "string"
      }
    ],
    "applicationsCount": 42.0,
    "featuredApplications": [
      {
        "id": "string",
        "name": "string",
        "type": "Native"
      }
    ]
  }
]