---
title: "List roles"
method: GET
path: "/user-service/roles"
tags: ["Roles"]
---

# List roles

`GET /user-service/roles`

Retrieve a list of roles for the specified account, including both account-specific roles and Firefly-managed (system-wide) roles. Firefly-managed roles have account_id as empty and are marked with fireflyManaged=true. For Firefly-managed roles, attached_users and team_names are filtered to show only those from the requesting account.

## Query parameters

- `limit` integer
- `offset` integer
- `search` string

## Response `200`

Array of roles

- RoleListResponse
  - `roles` Role[]
    - `id` string, uuid, required — Unique identifier for the role
    - `account_id` string, required — Account identifier this role belongs to
    - `name` string, required — Role name
    - `description` string, nullable — Role description
    - `integrationIds` string[] — Optional list of integration IDs to restrict role's access to specific integrations
    - `providers` string[] — Optional list of provider types to restrict role's access to specific providers
    - `scopes` RoleScope[], required — List of scopes/permissions assigned to this role
      - `scope_id` integer, required — ID of the scope definition
      - `scope_name` string, required — Name of the scope (e.g., inventory:read, workflows:*)
    - `attached_users` RoleUser[], required — Details of users that have this role assigned (name and profile photo). For Firefly-managed roles, only users from the requesting account are included.
      - `name` string, required — User's name
      - `profile_photo` string, nullable — URL to user's profile photo
    - `team_names` string[], required — Names of teams that have this role assigned. For Firefly-managed roles, only teams from the requesting account are included.
    - `firefly_managed` boolean, required — Whether this role is managed by Firefly (system-wide, non-editable role)
    - `created_at` string, date-time, required — When the role was created
    - `updated_at` string, date-time, required — When the role was last updated
  - `total_count` integer — Total number of roles matching the filter criteria

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden

---

[API](https://skmtc.net/firefly/apis/firefly-user-management-service-api.md) · [All operations](https://skmtc.net/firefly/apis/firefly-user-management-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/firefly/firefly-user-management-service-api/revisions/3d5d69795558/schema)