---
title: "Lists the roles accounts can hold: built-in first (highest rank first), then custom roles by name."
method: GET
path: "/api/v1/roles"
tags: ["Roles"]
---

# Lists the roles accounts can hold: built-in first (highest rank first), then custom roles by name.

`GET /api/v1/roles`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/roles`
- Auth: HTTP bearer

Requires `ManageUsers`. Roles are few, so this collection is <b>not</b> cursor-paginated:
everything comes back in one response with `nextCursor` always `null`. Sends a weak
`ETag`. Example: `GET /api/v1/roles`.
Also available as CSV (`Accept: text/csv` or `?format=csv`); paging cursor in `X-Next-Cursor`.

## Query parameters

- `format` 'csv'

## Response `200`

All roles.

- PagedResponseOfRoleDto: One page of a cursor-paginated /api/v1 collection (API_AND_MCP.md: `?after=<syncId>&limit=`).
  - `items` RoleDto[]: Items of this page in ascending creation order.
    - `id` integer, nullable: Custom role id (use it as `customRoleId` / in `customRoleIds` on the user endpoints); null for a built-in role. Example: `4`.
    - `name` string: Role name; for a built-in role this is the value to send as `role`. Example: `"Manager"`.
    - `description` string: What the role is for. Example: `"Manager with inventory and location management access"`.
    - `isBuiltIn` boolean: True for OrganizationAdmin / Manager / User, which cannot be edited.
    - `rank` integer: Hierarchy rank: OrganizationAdmin 3, Manager 2, User 1; custom roles 0 (they add permissions, not rank).
    - `permissions` string[]: Permissions the role grants, as FlexPermissions names. Example: `["ViewInventory", "ManageJobs"]`.
    - `createdAt` string, date-time, nullable: UTC creation time (ISO-8601); null for built-in roles.
    - `updatedAt` string, date-time, nullable: UTC last modification time (ISO-8601); null for built-in roles.
  - `nextCursor` string, nullable: SyncId of the last item; pass it back as `?after=` to fetch the next page. `null` when this is the last page.

## Other responses

- `304`: Unchanged since the supplied `If-None-Match`.
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too Many Requests

---

[API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)