---
title: "Create role"
method: POST
path: "/v1/roles"
tags: ["roles"]
---

# Create role

`POST /v1/roles`

## Request

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

Creates a custom role. Provide `name` and `permissions`, a list of `resource.action` strings or `"all"`. You cannot create a role that holds permissions you do not hold yourself.

**Notes.**
- `permissions`, `features` and `scope` are stored as sent: the handler does not check their shape, so a malformed value is stored and read back as it was written.
- `builtIn` in the body is ignored.

## Request body

- object
  - `name` string, required: Required on create.
  - `color` string
  - `description` string
  - `permissions` union: You must hold every permission you grant, workspace-wide. Default `[]`.
    - 'all'
    - string[]
  - `features` union: Default `[]`.
    - 'all'
    - string[]
  - `scope` union: Default `{ "kind": "workspace" }`.
    - object
      - `kind` 'workspace', required
    - object
      - `kind` 'org-units', required
      - `orgUnitIds` string[], required: The locations (and their subtrees) where the role applies.
  - `character` string, nullable

## Response `201`

Success.

- object
  - `data` Role, required: A named set of permissions assigned to people at locations.
    - `id` string, required
    - `name` string, required
    - `color` string, nullable, required: Display style for the role chip.
    - `description` string, required: Empty string when not set.
    - `builtIn` boolean, required: A role that every workspace starts with (Owner, Admin, Finance, Content Manager, Approver, Local Manager, Installer, Viewer). It cannot be deleted. The Owner role's permissions, features and scope cannot be changed; the other built-in roles can be edited.
    - `permissions` union, required: `resource.action` permissions, or `"all"` (every permission, now and later).
      - 'all'
      - string[]
    - `features` union, required: Feature keys the role unlocks, or `"all"`.
      - 'all'
      - string[]
    - `scope` union, required: Where the role applies: the whole workspace, or only the listed locations.
      - object
        - `kind` 'workspace', required
      - object
        - `kind` 'org-units', required
        - `orgUnitIds` string[], required: The locations (and their subtrees) where the role applies.
    - `character` string, nullable, required: A decorative label. Not used for access.
    - `memberCount` integer, required: Role assignments that use this role (one per person per location).
    - `createdAt` string, required: ISO-8601 timestamp (UTC).
    - `updatedAt` string, required: ISO-8601 timestamp (UTC).

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: `permissions` holds a permission you do not hold workspace-wide.
- `422`: `name` missing.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/7c2741bcdb16?raw)