---
title: "Get the roles the credential creator can see."
method: GET
path: "/api/v2/roles"
tags: ["Roles"]
---

# Get the roles the credential creator can see.

`GET /api/v2/roles`

## Request

- Base URL: `https://app.blackkitetech.com`
- URL: `https://app.blackkitetech.com/api/v2/roles`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://app.blackkitetech.com//api/v2/oauth/token`
- TypeScript: <https://skmtc.dev/blackkitetech/apis/black-kite-api/docs/api/v2/roles/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the roles visible to the user who created this credential, including visible legacy roles. Requires the "User Access Management - Read" permission. When User Access Management for groups has not been enabled for the tenant, the call is rejected before roles are read.

## Query parameters

- `page_number` integer
- `page_size` 10 | 20 | 30 | 50 | 100 | 250

## Response `200`

A bare array. Field order is RoleId, Name, Description, NumberOfCompanyPermissions, NumberOfTenantPermissions, NumberOfGroups, Permissions.

- Role[]
  - `RoleId` integer, required: The id of the role.
  - `Name` string, required: The display name of the role.
  - `Description` string, required: A short description of the role.
  - `NumberOfCompanyPermissions` integer, required: The number of company-scoped permissions the role grants.
  - `NumberOfTenantPermissions` integer, required: The number of tenant-scoped permissions the role grants.
  - `NumberOfGroups` integer, required: The number of groups the role is assigned to.
  - `Permissions` RolePermission[], required: The licensed permissions the role grants, limited to the permissions the credential creator can grant.
    - `PermissionName` string, required: The display name of the permission, as returned by GET /api/v2/permissions.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `default`: Failure

## Changes

- **2026-10-23** `fc42796447f4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/blackkitetech/apis/black-kite-api/changes/api/v2/roles/get.md)

---

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