---
title: "Create a role"
method: POST
path: "/user-service/roles"
tags: ["Roles"]
---

# Create a role

`POST /user-service/roles`

Create a new role with specified permissions

## Request body

- RoleCreateRequest
  - `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` RoleScopeInput[], required — List of scopes to assign to the role
    - `scope_id` integer, required — ID of the scope to assign to the role

## Response `201`

Created role

- RoleResponse
  - `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

## 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)