---
title: "List shareable people and roles"
method: GET
path: "/v1/shares/directory"
tags: ["shares"]
---

# List shareable people and roles

`GET /v1/shares/directory`

## Request

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

List the people and roles a share can target, including id, display name, and, for roles, colour and member count. Available to anyone holding a share permission on any content, rather than requiring full user directory access. People are listed only from the caller's own workspace: a franchise child workspace sees its own people, never the parent's or another child workspace's. Email is returned only for people the caller can see with the user view permission; otherwise it is null. A role's member count counts only the listed people.

**Notes.**
- Besides the `screen.view` gate, the caller needs at least one share permission somewhere.
- People stop at the child-workspace line: a franchise child workspace sees only its own people, and the parent does not see into a child. `email` needs `user.view` reaching that person, else it is null.

## Response `200`

Success.

- object
  - `data` object, required
    - `users` object[], required: People in the workspace the caller shares from (active and invited; never across a franchise child-workspace line).
      - `id` string, required
      - `name` string, required
      - `email` string, nullable, required: Only for people the caller could read with `user.view`; null otherwise.
    - `roles` object[], required: Every role in the workspace.
      - `id` string, required
      - `name` string, required
      - `color` string, nullable, required
      - `memberCount` integer, required: Members among the people listed above.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: You hold no share permission (`playlist.share`, `media.share`, …) anywhere.
- `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)