---
search:
  tags:
    - Layouts
    - PUT
seo:
  description: >-
    Add and remove a layout's grants and set whether it is restricted,…
    Reference for the PUT /v1/layouts/id/{layout_id}/access endpoint in the
    Roboto REST API.
sidebar:
  label: Edit layout access
  badge: PUT
title: Edit layout access
type: openapi-operation
---
Add and remove a layout's grants and set whether it is restricted, then list who it is shared with.

Restricting a layout makes it personal: only its creator, the people and groups it is shared with, the org's admins
and Roboto staff open it. Unrestricting it shares it with the whole org. Either sets its ``accessibility``, which
only its creator and the org's admins may change. Adding or removing a grant requires permission to change the
layout, which its creator, the org's admins and the holders of an ``editor`` grant have. A ``viewer`` opens the
layout; an ``editor`` also changes it, but neither renames nor deletes it.

A request that does both must satisfy both, and a refused request changes nothing; a refused check answers 401. A
request that changes nothing answers as ``GET`` does and requires only permission to open the layout. A layout that
does not exist, or is not in the caller's org, answers 404.

Refused with 400 when a grant names an unknown subject kind or role, a subject without the id its kind needs, the
members of another org, a group that is not one of the layout's org's groups, or the role ``deleter``; when making
the layout personal or shared clashes with another layout's name, 409. Where the deployment decides who may open a
layout from OpenFGA rather than from Roboto's own tables, a grant is refused with 400. On a deployment in store mode
``tables_only``, a grant to a group is refused with 401 unless Roboto has turned groups on for the layout's org.

#### Access control
 - Restricted tokens need the API scope `api.everything_else`

`PUT /v1/layouts/id/{layout_id}/access`

**Request body** (`application/json`, required)

- `add` (GrantBody[])
- `remove` (GrantBody[])
- `restricted` (boolean | null)

Request body example:

```json
{
  "add": [
    {
      "subject": {
        "kind": "string",
        "id": null
      },
      "role": "string"
    }
  ],
  "remove": [
    {
      "subject": {
        "kind": "string",
        "id": null
      },
      "role": "string"
    }
  ],
  "restricted": null
}
```

**Responses**

- `200` — OK
- `400` — A conversation with Roboto's AI is longer than the AI model can read at once. The conversation's messages and tool results, together with the AI's instructions, exceed the model's context window. The exception does not carry the token count or the model's limit.
- `401` — The caller's token is expired or malformed.
- `403` — The request would take the user or organization past a limit on a resource, such as AI credits.
- `404` — The request names an API route Roboto does not serve.
- `409` — The request conflicts with an existing resource, such as by giving a name another resource already has.
- `410` — The resource the request names is missing or has expired.
- `500` — Roboto reported an error that this release of the SDK cannot match to a specific exception class. Reported for an element of a :py:class:\`\~roboto.http.BatchResponse\` whose error names a code this release defines no class for, or that arrived without a code, without a message, or as text that is not an error envelope at all. It carries whatever code and message Roboto sent, so a caller handling the failure still learns what went wrong; when no message could be read, the message is the error's raw text. :py:meth:\`\~roboto.domain.devices.Device.create\_session\` raises it, and :py:meth:\`\~roboto.domain.devices.Device.create\_sessions\` lists it in the batch's :py:attr:\`\~roboto.http.BatchResponse.failed\`. The error envelope carries no status code, so \`\`http\_status\_code\`\` reports the 500 inherited from \`\`RobotoDomainException\`\` rather than the status the failure had.
- `501` — The request asks for an operation this deployment of Roboto does not provide.
- `503` — Roboto could not accept the request, such as under heavy load. Retrying later may succeed.
- `504` — Roboto ran out of time while processing the request. Retrying may succeed.
- `507` — The response to the request is larger than Roboto can send. Retrying the same request fails the same way; request less data at a time.

Response example, 200:

```json
{
  "data": {
    "restricted": true,
    "grants": [
      {
        "subject": {
          "kind": "user",
          "id": null
        },
        "role": "viewer"
      }
    ]
  }
}
```
