# Set a board's general access

> Page: https://docs.plotwork.dev/api/put-orgs-org-boards-board-access. Index of every page: https://docs.plotwork.dev/llms.txt

Opens the board to the whole organisation with view or edit, or only to the people and groups added.

`PUT /orgs/{org}/boards/{board}/access`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Set a board's general access. |
| What does it take? | A JSON body of type [`SetBoardAccessBody`](https://docs.plotwork.dev/api/schemas.md#setboardaccessbody). |
| What does it return? | Status 200 with a body of type [`BoardAccess`](https://docs.plotwork.dev/api/schemas.md#boardaccess). |
| What can go wrong? | `400` the body is not valid; `401` not signed in; `403` boards are not turned on for this organisation (boards.not_enabled), the caller may look but not change it (boards.forbidden), or the request came from an origin that may not make changes; `404` no such organisation, board or tab, or the board is not open to the caller: the cases look alike; `429` too many requests; `503` organisations or boards are not set up on this server. Every failure uses the one error envelope. |

## What it does

Opens the board to the whole organisation with view or edit, or only to the people and groups added. The people who manage the board may. Narrowing it closes every live connection, which reconnects with what is left. Audited as orgs.board.access.

## Path parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `org` | `string` | yes | The organisation's id or its slug. |
| `board` | `string` | yes | The board's id: 22 letters and digits. |

## Request body

The body has the type [`SetBoardAccessBody`](https://docs.plotwork.dev/api/schemas.md#setboardaccessbody).

| Field | Type | Required | Description |
|---|---|---|---|
| `access` | `"org" \| "restricted"` | yes |  |
| `orgRole` | `"view" \| "edit"` | yes |  |
| `guestLink` | `boolean` | no | Anyone signed in with the link may watch the board, read only. Left out, it stays as it is. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | Who may open the board. | [`BoardAccess`](https://docs.plotwork.dev/api/schemas.md#boardaccess) |
| 400 | The body is not valid. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 403 | Boards are not turned on for this organisation (boards.not_enabled), the caller may look but not change it (boards.forbidden), or the request came from an origin that may not make changes. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | No such organisation, board or tab, or the board is not open to the caller: the cases look alike. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | Organisations or boards are not set up on this server. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`BoardAccess`](https://docs.plotwork.dev/api/schemas.md#boardaccess).

| Field | Type | Required | Description |
|---|---|---|---|
| `access` | `"org" \| "restricted"` | yes |  |
| `orgRole` | `"view" \| "edit"` | yes |  |
| `grants` | `BoardGrant[]` | yes |  |
| `grants[].kind` | `"user" \| "group"` | yes |  |
| `grants[].id` | `string` | yes |  |
| `grants[].name` | `string` | yes | A member's email address, or a group's name. |
| `grants[].role` | `"view" \| "edit" \| "manage"` | yes | view: look; edit: change the tabs; manage: also change who may open the board. |
| `joinLinks` | `BoardJoinLink[]` | yes |  |
| `joinLinks[].id` | `string` | yes |  |
| `joinLinks[].role` | `"view" \| "edit"` | yes |  |
| `joinLinks[].createdAt` | `integer` | yes |  |
| `joinLinks[].expiresAt` | `integer` | yes |  |
| `canManage` | `boolean` | yes |  |
| `guestLink` | `boolean` | yes | True when anyone signed in with the link may watch the board, as the board chose. |
| `guests` | `"ok" \| "off" \| "confidential"` | yes | Whether guests may open the board now: ok, or off when the owner does not allow guests on boards, or confidential for a Confidential board. Only ok lets a guest in. |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |