---
title: "List roles"
method: GET
path: "/v2/roles"
tags: ["Roles"]
---

# List roles

`GET /v2/roles`

## Request

- Base URL: `https://yourbaseurl.talon.one`
- URL: `https://yourbaseurl.talon.one/v2/roles`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/talon/apis/management-api/docs/v2/roles/get.ts> (a function with typed inputs; its response is checked against the schema)

> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

List the roles defined in the deployment.

The roles returned depend on the role of the user calling this endpoint:
- If the user has an admin role, all roles defined in the deployment are returned.
- If the user does not have an admin role, only the roles currently assigned to this user are returned.

If your identity provider provisions roles through SCIM, any admin roles it defines are not included in this list.

To view the details of a specific role, use the [Get role](https://docs.talon.one/management-api#tag/Roles/operation/getRoleV2) endpoint.

## Response `200`

OK

- object
  - `totalResultSize` integer, required: The total number of roles returned.
  - `data` RoleV2[], required: The list of roles.
    - `id` integer, required: The internal ID of this entity.
    - `created` string, date-time, required: The time this entity was created.
    - `modified` string, date-time, required: The time this entity was last modified.
    - `accountId` integer, required: The ID of the account that owns this entity.
    - `name` string: Name of the role.
    - `description` string: Description of the role.
    - `permissions` RoleV2Permissions: The permissions that this role gives.
      - `permissionSets` RoleV2PermissionSet[]: List of grouped logical operations referenced by roles.
        - `name` string, required: Name of the permission set.
        - `logicalOperations` string[], required: List of logical operations in the permission set.
      - `roles` RoleV2RolesGroup: A map of target entities to their permission sets.
        - `applications` RoleV2Application: A map of the link between the Application, campaign, or draft campaign-related permission set and the Application ID the permissions apply to.
        - `loyaltyPrograms` RoleV2LoyaltyGroup: A map of the link between the loyalty program-related permission set and the loyalty program ID the permissions apply to.
        - `campaignAccessGroups` RoleV2CampaignAccessGroup: A map of the link between the campaign access group-related permission set and the campaign access group ID the permissions apply to.
        - `account` string: Name of the account-level permission set.
      - `thresholds` RolesV2Thresholds[]: Support user limits for actions that require admin approval within the given application.
        - `loyaltyProgramId` integer: Identifier of the loyalty program. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint.
        - `loyaltyPointsLimit` integer: Maximum number of loyalty points a support user can award without approval.
    - `members` integer[]: A list of user IDs the role is assigned to.
    - `isReadonly` boolean: Identifies if the role is read-only. For read-only roles, you can only assign or unassign users. You cannot edit any other properties, such as the name, description, or permissions. This property cannot be set for new or existing roles. It is reserved for predefined roles, such as the Talon.One support role.

---

[API](https://skmtc.dev/talon/apis/management-api.md) - [All operations](https://skmtc.dev/talon/apis/management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/talon/apis/management-api/revisions/7ef1b9504c3a?raw)