Roles API

GET/v1/roles

Returns the workspace's roles, both built-in and custom, with the permissions each one carries. **Notes.** - Not paginated.

curl "https://api.brixsignage.com/v1/roles" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/roles

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 application/json

curl -X POST "https://api.brixsignage.com/v1/roles" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Store manager","permissions":["screen.view","screen.cast","media.view","media.create"]}'

Response 201 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 `permissions` holds a permission you do not hold workspace-wide.

Response 422 `name` missing.

Response 5XX Server error. The body carries a `requestId` to quote to support.

GET/v1/roles/{id}

Returns one role with its full list of permissions.

curl "https://api.brixsignage.com/v1/roles/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such role in this workspace (or it is deleted).

Response 5XX Server error. The body carries a `requestId` to quote to support.

PATCH/v1/roles/{id}

Updates a role. The same rule as creating a role applies: you cannot add or remove a permission you do not hold yourself. Only a signed-in account owner can take full ownership away from a role that people hold; an API key cannot. On a built-in role, only the name, color and description change; its permissions, features and scope stay fixed. **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. - On a built-in role, permissions, features and scope are ignored without an error; only name, color, description and character change.

Request body application/json

curl -X PATCH "https://api.brixsignage.com/v1/roles/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You would add or remove a permission you do not hold workspace-wide, or change `scope` of a role whose permissions you do not hold workspace-wide; `owner_required`: the change takes full ownership away from a role people hold, and the caller is not a signed-in owner (an API key never is).

Response 404 No such role in this workspace.

Response 409 `last_owner_role`: this is the only role with full ownership.

Response 5XX Server error. The body carries a `requestId` to quote to support.

DELETE/v1/roles/{id}

Soft-deletes a custom role. The role can later be restored. Refuses the request while anyone is still assigned to the role.

curl -X DELETE "https://api.brixsignage.com/v1/roles/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such role in this workspace.

Response 409 `protected` (a built-in role), `last_owner_role`, or `in_use` (people still hold the role).

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/roles/{id}/restore

Restores a previously deleted custom role. Requires the same permission needed to delete a role. **Notes.** - Answers the whole restored role, not the { id, restored } acknowledgement other restores use.

curl -X POST "https://api.brixsignage.com/v1/roles/{id}/restore" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such role in this workspace.

Response 409 `not_deleted`: the role is not deleted.

Response 5XX Server error. The body carries a `requestId` to quote to support.