---
title: "List user role assignments"
method: GET
path: "/api/v1/users/roles"
tags: ["Users"]
---

# List user role assignments

`GET /api/v1/users/roles`

## Request

- Base URL: `https://api.getcortexapp.com`
- URL: `https://api.getcortexapp.com/api/v1/users/roles`
- Auth: HTTP bearer

Returns the role assignments for every user in your Cortex tenant, intended for access reviews and access governance reporting. Each entry lists the user along with their assigned built-in (BASIC) and CUSTOM roles. Requires the View Roles permission; assign it to a custom role to issue a least-privilege API key for automated reporting.

## Query parameters

- `email` string[]
- `pageSize` integer, required
- `page` integer, required

## Response `200`

Successfully retrieved user role assignments

- UserRoleAssignmentsResponse
  - `page` integer, required: Current page number, 0-indexed
  - `total` integer, required: Total number of results
  - `totalPages` integer, required: Total number of pages
  - `users` UserRoleAssignment[], required: User role assignments for the current page
    - `email` string, required: Email address of the user
    - `name` string, required: Display name of the user
    - `roles` AssignedRole[], required: Roles assigned to the user
      - `name` string: Display name of the custom role; present only when type is CUSTOM
      - `role` string: Name of the built-in role; present only when type is BASIC
      - `tag` string: Tag of the custom role; present only when type is CUSTOM
      - `type` 'BASIC' | 'CUSTOM', required: Whether this is a built-in (BASIC) or CUSTOM role

## Other responses

- `401`: Authentication required
- `403`: Caller does not have the View Roles permission
- `429`: The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

## Changes

- **2026-11-03** `a7b058663c95`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cortex/apis/cortex-api/changes/api/v1/users/roles/get.md)

---

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