---
title: "Get list of roles"
method: GET
path: "/v2/iam/roles"
tags: ["IAM"]
---

# Get list of roles

`GET /v2/iam/roles`

Returns a list of roles. You need the View roles in organization permission to use the account_identifier parameter.


You need the "View roles in account" permission to use this endpoint.

## Query parameters

- `name_contains` string
- `permissions` string[]
- `account_identifier` string, uuid
- `page_number` integer
- `page_size` integer
- `sort` string[]

## Response `200`

OK

- IdentityPaginatedResponseRoleResponse
  - `first` string, required — The URL path to the first page.
  - `next` string, nullable — The URL path to the next page.
  - `prev` string, nullable — The URL path to the previous page.
  - `roles` union[], required
    - union
      - IdentityBuiltInRoleResponse
        - `description` string, required — Description of the role.
        - `identifier` string, uuid, required — The unique identifier of the role.
        - `name` string, required — Name of the role.
        - `users_assigned_count` integer, required — Number of users assigned.
      - IdentityCustomRoleResponse
        - `account_identifier` string, uuid, required — The account identifier of the role.
        - `created_at` string, date-time, required — Date and time the role was last created.
        - `created_by` string, uuid — Created by identifier
        - `description` string, required — Description of the role.
        - `identifier` string, uuid, required — The unique identifier of the role.
        - `name` string, required — Name of the role.
        - `updated_at` string, date-time, required — Date and time the role was last updated.
        - `updated_by` string, uuid — Updated by identifier
        - `users_assigned_count` integer, required — Number of users assigned.
  - `self` string, required — The URL path to the current page.
  - `total_count` integer, nullable — Total number of items.

---

[API](https://skmtc.dev/complyadvantage/apis/mesh-api.md) · [All operations](https://skmtc.dev/complyadvantage/apis/mesh-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/complyadvantage/mesh-api/revisions/fdaac4351d85/schema)