## Set who may use a folder (tenant:dms:admin)

`PUT /api/dms/v1/folders/{id}/access`

Module: DMS · operationId: `setFolderAccess` · Tag: Folders · Auth: access token (`Authorization: Bearer <accessToken>`)

Replaces the folder's entries (at most 100). An empty list lifts the folder's own restriction;
restricted folders above still apply. Recorded in the audit trail (`FOLDER_ACCESS`); the
documents below are announced again with `dms.document.filed`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `entries` (array of FolderAccessEntry, required): The new entries; replaces all entries of the folder (empty lifts the restriction)
  - `level` (string, required): READ: read only; WRITE: read and change (one of `READ`, `WRITE`)
  - `principalId` (string, required): E-mail (USER) or key group id (GROUP)
  - `principalType` (string, required): USER: a person by e-mail; GROUP: a DMS key group (one of `USER`, `GROUP`)
  - `name` (string): Name of the key group (responses only)

Example:

```json
{
  "entries": [
    {
      "level": "WRITE",
      "principalId": "anna.schmidt@beispiel.de",
      "principalType": "USER"
    }
  ]
}
```

### Responses

- **200** Access (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `entries` (array of FolderAccessEntry, required): Access entries of the folder itself; empty: not restricted by this folder
  - `level` (string, required): READ: read only; WRITE: read and change (one of `READ`, `WRITE`)
  - `principalId` (string, required): E-mail (USER) or key group id (GROUP)
  - `principalType` (string, required): USER: a person by e-mail; GROUP: a DMS key group (one of `USER`, `GROUP`)
  - `name` (string): Name of the key group (responses only)
- `folderId` (string (uuid), required): Folder id
- `inheritedFrom` (array of FolderRef, required): Restricted folders above, top level first
  - `id` (string (uuid), required): Folder id
  - `name` (string, required): Folder name

Example 200 answer:

```json
{
  "entries": [
    {
      "level": "WRITE",
      "principalId": "christina.adler@muster-it.example",
      "principalType": "USER"
    },
    {
      "level": "READ",
      "name": "Geschäftsführung",
      "principalId": "5d7f9b1d-3e5a-4c7b-9d1f-7b9d1f3a5c7e",
      "principalType": "GROUP"
    }
  ],
  "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "inheritedFrom": [
    {
      "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
      "name": "Buchhaltung"
    }
  ]
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/dms/v1/folders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/access' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"entries":[{"level":"WRITE","principalId":"anna.schmidt@beispiel.de","principalType":"USER"}]}'
```
