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

# List all roles.

`GET /roles`

## Request

- Base URL: `https://console.jumpcloud.com/api/v2`
- URL: `https://console.jumpcloud.com/api/v2/roles`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/jumpcloud/apis/jumpcloud-api-2/docs/roles/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns a paginated list of all roles.

Catalog visibility depends on authenticated organization/provider context.

Organization-scoped requests (Direct, OU, MSP customer org) return the
organization catalog. MSP provider-only requests return either the provider
management catalog or, when `purpose=assignment`, the provider assignment
catalog.

Route availability is context-dependent: MSP provider-only requests require
SP-10009-custom-role-mtp; all other contexts require na-1377-customroles-api.

## Query parameters

- `filter` string[]
- `limit` integer
- `skip` integer
- `sort` string[]
- `purpose` 'assignment'

## Headers

- `x-org-id` string
- `x-provider-id` string
- `x-total-count` integer

## Response `200`

Successfully retrieved roles.

- RoleList
  - `totalCount` integer: Total number of roles available.
  - `results` Role[]: List of roles
    - `id` string: ID of the role
    - `name` string, required: Name of the role
    - `scopes` string[], required: List of permission scopes associated with this role.
    - `providerId` string: ID of the provider associated with this role.
    - `organizationIds` string[]: List of organization IDs this role is associated with.
    - `description` string: Description of the role and its purpose
    - `createdBy` string: ID of the user who created this role
    - `lastUpdatedBy` string: ID of the user who last updated this role
    - `isCustom` boolean: Indicates if this is a custom role (true) or a system role (false)
    - `ownerType` 'provider': Owner of the custom role. Set to `provider` for provider-owned (MSP) custom roles; omitted for organization-owned roles.

## Other responses

- `401`: Unauthenticated
- `403`: Unauthorized
- `404`: Not Found
- `500`: Internal Server Error

---

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