# Set board access settings

> Set a team board to private, shared with the team, or restricted to named board members.

Canonical page: https://www.rundiffusion.com/docs/api/boards/access
Endpoint: PUT /api/v2/boards/{board_id}/access
Authorization: OAuth device flow or Personal API Access Token or Company API Access Token

---

Who can reach a team board. This is the one call that changes `access_level`, and
the same call sets the board member list, because the two only make sense together.

`PUT /api/v2/boards/{board_id}/access`

Authorization: OAuth device flow or Personal API Access Token or Company API Access Token

| Level | Who can reach the board |
| --- | --- |
| `PRIVATE` | the owner alone |
| `SHARED` | everyone on the team |
| `RESTRICTED` | only the board members you name, plus the owner |

Personal boards have no access settings: there is nobody to share with, so this
endpoint answers `400 INVALID_REQUEST` for one.

## Who can change access

Stricter than editing a board's name, because it changes who can see work:

- to **`SHARED` or `RESTRICTED`** you need **Can manage Shared assets**
  (`SHARE_ASSETS`). If you are not the owner you also need **Can manage
  everyone's generations and boards** (`MANAGE_ALL_GENERATIONS`).
- to **`PRIVATE`** the owner may always do it, and so may a holder of **Can manage
  everyone's generations and boards**.

Owning a board is therefore not enough to share it: a team that withholds **Can
manage Shared assets** from a role keeps that role's boards private, which is the
point of the permission.

## Request

**Headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer token. This endpoint accepts an OAuth device flow token, a Personal API Access Token, or a Company API Access Token. See [Authentication](/docs/api/authentication). |

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `board_id` | string | Yes | The board to change. |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `access_level` | string | Yes | The level to set. One of: `PRIVATE`, `SHARED`, `RESTRICTED` |
| `member_user_ids` | array | No | The complete board member list for RESTRICTED, replacing whatever was there. Send user IDs, as returned by [Identity](/docs/api/me). The owner is always a board member and does not need listing. Ignored at the other levels, where membership is not what decides access. |

cURL:

```bash
curl -X PUT "https://api2.rundiffusion.com/api/v2/boards/$BOARD_ID/access?team_id=$TEAM_ID" \
  -H "Authorization: Bearer $RUNDIFFUSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"access_level": "RESTRICTED", "member_user_ids": ["k3PqV9…"]}'
```

JavaScript:

```javascript
const board = await fetch(
  `https://api2.rundiffusion.com/api/v2/boards/${boardId}/access?team_id=${teamId}`,
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${process.env.RUNDIFFUSION_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      access_level: 'RESTRICTED',
      member_user_ids: ['k3PqV9…'],
    }),
  },
).then(r => r.json());
```

Python:

```python
board = requests.put(
    f"{BASE}/boards/{board_id}/access",
    headers=HEADERS,
    params={"team_id": team_id},
    json={"access_level": "RESTRICTED", "member_user_ids": ["k3PqV9…"]},
).json()
```

## Response

`200 OK` with the full board, in the same shape
[Get a board](/docs/api/boards/get) returns, so `members` reflects the change you
just made.

```json
{
  "id": "Tq8vNc…",
  "title": "Hero shots",
  "access_level": "RESTRICTED",
  "owner_user_id": "k3PqV9…",
  "team_id": "Kp7mZq…",
  "nodes": [],
  "members": [
    {
      "user_id": "k3PqV9…",
      "email": "sam@example.com",
      "created_at": "2026-08-01T09:20:00+00:00"
    },
    {
      "user_id": "m8ZtLq…",
      "email": "alex@example.com",
      "created_at": "2026-08-01T09:20:00+00:00"
    }
  ]
}
```

> **member_user_ids replaces, it does not append**
>
> Whatever you send becomes the entire board member list. To add one person, read the
> board, append to the `user_id` values you got back, and send the result. Sending
> a single ID sets the board to exactly that person plus the owner, removing
> everyone else.
>
> Replacing rather than appending is deliberate: the same request twice leaves the
> board in the same state, so a retry after a timeout cannot half-apply.

Leaving `RESTRICTED` clears the board member list. Setting it back later starts from the
owner alone, so keep your own record if you intend to restore a group.

## Errors

**Status codes**

| Name | Type | Description |
| --- | --- | --- |
| `400` | INVALID_REQUEST | An unknown access level, a personal board (which has no access settings), or more board member changes than one request allows. |
| `401` | TOKEN_INVALID | Missing or invalid credential. |
| `403` | PERMISSION_DENIED | You lack the permission for the level you asked for. Sharing needs Can manage Shared assets; doing it to somebody else's board also needs Can manage everyone's generations and boards. |
| `404` | BOARD_NOT_FOUND | No such board, or not one this credential can see. |
| `429` | RATE_LIMITED | Too many requests. See [Rate limits](/docs/api/rate-limits#boards). |