---
title: "Get role"
method: GET
path: "/v1/roles/{id}"
tags: ["roles"]
---

# Get role

`GET /v1/roles/{id}`

## Request

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

Returns one role with its full list of permissions.

## Path parameters

- `id` string, required

## Response `200`

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`: The token lacks the permission this operation needs (see `x-brix-permission`).
- `404`: No such role in this workspace (or it is deleted).
- `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/02fd3665dc7d?raw)