> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/guides/account-and-mailbox-permissions.md).

# Account and Mailbox Permissions

This document contains endpoints for retrieving, adding, replacing, and removing permissions and roles assigned to users in account and mailbox contexts.

### Business goals

Account and Mailbox Permissions endpoints support the following business goals:

* **Control account administration:** Grant users access to account-level operations
* **Control mailbox access:** Define what users can do inside a specific mailbox
* **Reuse access configurations:** Assign permission roles instead of managing every permission separately
* **Extend existing access:** Add permissions or roles without removing current assignments
* **Replace access configurations:** Set the complete permission and role configuration for a user
* **Revoke access selectively:** Remove one permission, one role, or all access in the selected context

### Endpoint summary

#### Account permissions

<table><thead><tr><th width="99">Method</th><th width="348">Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/api/v1/permission/{userUuid}/account/{accountUuid}</code></td><td>Retrieve account permissions and roles</td></tr><tr><td><code>PATCH</code></td><td><code>/api/v1/permission/{userUuid}/account/{accountUuid}</code></td><td>Add account permissions and roles</td></tr><tr><td><code>PUT</code></td><td><code>/api/v1/permission/{userUuid}/account/{accountUuid}</code></td><td>Replace account permissions and roles</td></tr><tr><td><code>DELETE</code></td><td><code>/api/v1/permission/{userUuid}/account/{accountUuid}/{permissionId}</code></td><td>Remove one account permission</td></tr><tr><td><code>DELETE</code></td><td><code>/api/v1/permission/{userUuid}/account/{accountUuid}/role/{roleUuid}</code></td><td>Remove one account role</td></tr><tr><td><code>DELETE</code></td><td><code>/api/v1/permission/{userUuid}/account/{accountUuid}</code></td><td>Remove the user from the account</td></tr></tbody></table>

#### Mailbox permissions

<table><thead><tr><th width="101.33331298828125">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td><code>PATCH</code></td><td><code>/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}</code></td><td>Add mailbox permissions and roles</td></tr><tr><td><code>PUT</code></td><td><code>/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}</code></td><td>Replace mailbox permissions and roles</td></tr><tr><td><code>DELETE</code></td><td><code>/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}/{permissionId}</code></td><td>Remove one mailbox permission</td></tr><tr><td><code>DELETE</code></td><td><code>/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}/role/{roleUuid}</code></td><td>Remove one mailbox role</td></tr><tr><td><code>DELETE</code></td><td><code>/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}</code></td><td>Remove all mailbox permissions and roles</td></tr></tbody></table>

### Permission assignment structure and headers

All permission operations require an API token in the `Authorization` header. Requests that add or replace permissions must also use `Content-Type: application/json`.

```http
Authorization: Bearer {token}
Content-Type: application/json
```

The request body used by `PATCH` and `PUT` contains two arrays:

```json
{
  "permissions": [
    123
  ],
  "roles": [
    "{roleUuid}"
  ]
}
```

Use permission IDs and role UUIDs returned by the [Permission Roles](/guides/permission-roles.md) endpoints. The `0` permission ID shown in Swagger is a schema example and must be replaced with a real permission ID.

An account role must be assigned through an account permission endpoint. A mailbox role must be assigned through a mailbox permission endpoint.

#### Path parameters

| Parameter      | Description                                 |
| -------------- | ------------------------------------------- |
| `userUuid`     | UUID of the user receiving or losing access |
| `accountUuid`  | UUID of the account                         |
| `mailboxUuid`  | UUID of the mailbox                         |
| `permissionId` | Numeric permission identifier               |
| `roleUuid`     | UUID of the assigned permission role        |

### Retrieve account permissions

Retrieve the current permissions and roles assigned to a user within an account. The response also contains basic information about the selected user.

```http
GET /api/v1/permission/{userUuid}/account/{accountUuid}
Authorization: Bearer {token}
```

A successful request returns `200 OK`.

{% tabs %}
{% tab title="Node.js" %}

```javascript
const response = await fetch(
  "https://api.docstudio.com/api/v1/permission/{userUuid}/account/{accountUuid}",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer {token}"
    }
  }
);

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

console.log(body);
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init(
    "https://api.docstudio.com/api/v1/permission/{userUuid}/account/{accountUuid}"
);

curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo(
    $curl,
    CURLINFO_RESPONSE_CODE
);

curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

echo $body;
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.get(
    "https://api.docstudio.com/api/v1/permission/{userUuid}/account/{accountUuid}",
    headers={
        "Authorization": "Bearer {token}",
    },
    timeout=30,
)

response.raise_for_status()
print(response.json())
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "net/http"
require "uri"

uri = URI(
  "https://api.docstudio.com/api/v1/permission/{userUuid}/account/{accountUuid}"
)

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer {token}"

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	request, err := http.NewRequest(
		http.MethodGet,
		"https://api.docstudio.com/api/v1/permission/{userUuid}/account/{accountUuid}",
		nil,
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	fmt.Println(string(body))
}
```

{% endtab %}

{% tab title="Java" %}

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/permission/{userUuid}/account/{accountUuid}"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .GET()
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " +
          response.statusCode() +
          "\n" +
          response.body()
      );
    }

    System.out.println(response.body());
  }
}
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using System.Net.Http.Headers;

using var client = new HttpClient();

using var request = new HttpRequestMessage(
    HttpMethod.Get,
    "https://api.docstudio.com/api/v1/permission/{userUuid}/account/{accountUuid}"
);

request.Headers.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

using var response =
    await client.SendAsync(request);

var body =
    await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: " +
        $"{(int)response.StatusCode}\n{body}"
    );
}

Console.WriteLine(body);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url 'https://api.docstudio.com/api/v1/permission/{userUuid}/account/{accountUuid}' \
  --header 'Authorization: Bearer {token}'
```

{% endtab %}
{% endtabs %}

The permission ID and role UUID shown here are examples. Replace them with actual assigned values.

### Practical example: Add account and mailbox access

A company has added an employee who needs access to account-level reporting and permission to review contracts in a mailbox. The integration adds the required account access first and then configures the employee’s mailbox access.

1. Retrieve available permission IDs and role UUIDs.
2. Assign the required account permissions and roles.
3. Assign the required mailbox permissions and roles.
4. Retrieve account permissions to confirm the assignment.

#### Add account permissions and roles

Use `PATCH` when existing assignments must remain unchanged. Permissions and roles already assigned to the user are ignored instead of being duplicated.

{% tabs %}
{% tab title="Node.js" %}

```javascript
const response = await fetch(
  "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer {token}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      permissions: [123],
      roles: ["{accountRoleUuid}"]
    })
  }
);
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$client = curl_init(
    "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}"
);

curl_setopt_array($client, [
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => json_encode([
        "permissions" => [123],
        "roles" => ["{accountRoleUuid}"]
    ]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Content-Type: application/json"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($client);
curl_close($client);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.patch(
    "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}",
    headers={
        "Authorization": "Bearer {token}"
    },
    json={
        "permissions": [123],
        "roles": ["{accountRoleUuid}"]
    }
)
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "json"
require "net/http"

uri = URI(
  "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}"
)
request = Net::HTTP::Patch.new(
  uri,
  {
    "Authorization" => "Bearer {token}",
    "Content-Type" => "application/json"
  }
)
request.body = {
  permissions: [123],
  roles: ["{accountRoleUuid}"]
}.to_json

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: uri.scheme == "https"
) { |http| http.request(request) }
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
    "bytes"
    "log"
    "net/http"
)

func main() {
    body := bytes.NewBufferString(`
{
  "permissions": [123],
  "roles": ["{accountRoleUuid}"]
}`)

    request, err := http.NewRequest(
        http.MethodPatch,
        "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}",
        body,
    )
    if err != nil {
        log.Fatal(err)
    }

    request.Header.Set("Authorization", "Bearer {token}")
    request.Header.Set("Content-Type", "application/json")

    response, err := http.DefaultClient.Do(request)
    if err != nil {
        log.Fatal(err)
    }
    defer response.Body.Close()
}
```

{% endtab %}

{% tab title="Java" %}

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class AddAccountAccess {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "permissions": [123],
              "roles": ["{accountRoleUuid}"]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}"
            ))
            .header("Authorization", "Bearer {token}")
            .header("Content-Type", "application/json")
            .method("PATCH", HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );
    }
}
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using System.Net.Http.Headers;
using System.Net.Http.Json;

using var client = new HttpClient();
using var request = new HttpRequestMessage(
    HttpMethod.Patch,
    "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}"
)
{
    Content = JsonContent.Create(new
    {
        permissions = new[] { 123 },
        roles = new[] { "{accountRoleUuid}" }
    })
};

request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer",
    "{token}"
);

using var response = await client.SendAsync(request);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request PATCH \
  "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "permissions": [123],
    "roles": ["{accountRoleUuid}"]
  }'
```

{% endtab %}
{% endtabs %}

Replace `123` with an actual account permission ID and replace `{accountRoleUuid}` with the UUID of an account role. A successful request returns `200 OK`.

Retrieve the account permission configuration to confirm the resulting assignment.

```http
GET /api/v1/permission/{userUuid}/account/{accountUuid}
Authorization: Bearer {token}
```

#### Add mailbox permissions and roles

Use the mailbox endpoint to grant access within a specific mailbox. Mailbox assignments do not replace or modify the user’s account-level permissions, and permissions or roles already assigned to the user are ignored instead of being duplicated.

{% tabs %}
{% tab title="Node.js" %}

```javascript
const response = await fetch(
  "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer {token}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      permissions: [456],
      roles: ["{mailboxRoleUuid}"]
    })
  }
);
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$client = curl_init(
    "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}"
);

curl_setopt_array($client, [
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => json_encode([
        "permissions" => [456],
        "roles" => ["{mailboxRoleUuid}"]
    ]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Content-Type: application/json"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($client);
curl_close($client);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.patch(
    "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}",
    headers={
        "Authorization": "Bearer {token}"
    },
    json={
        "permissions": [456],
        "roles": ["{mailboxRoleUuid}"]
    }
)
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "json"
require "net/http"

uri = URI(
  "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}"
)
request = Net::HTTP::Patch.new(
  uri,
  {
    "Authorization" => "Bearer {token}",
    "Content-Type" => "application/json"
  }
)
request.body = {
  permissions: [456],
  roles: ["{mailboxRoleUuid}"]
}.to_json

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: uri.scheme == "https"
) { |http| http.request(request) }
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
    "bytes"
    "log"
    "net/http"
)

func main() {
    body := bytes.NewBufferString(`
{
  "permissions": [456],
  "roles": ["{mailboxRoleUuid}"]
}`)

    request, err := http.NewRequest(
        http.MethodPatch,
        "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}",
        body,
    )
    if err != nil {
        log.Fatal(err)
    }

    request.Header.Set("Authorization", "Bearer {token}")
    request.Header.Set("Content-Type", "application/json")

    response, err := http.DefaultClient.Do(request)
    if err != nil {
        log.Fatal(err)
    }
    defer response.Body.Close()
}
```

{% endtab %}

{% tab title="Java" %}

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class AddMailboxAccess {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "permissions": [456],
              "roles": ["{mailboxRoleUuid}"]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}"
            ))
            .header("Authorization", "Bearer {token}")
            .header("Content-Type", "application/json")
            .method("PATCH", HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );
    }
}
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using System.Net.Http.Headers;
using System.Net.Http.Json;

using var client = new HttpClient();
using var request = new HttpRequestMessage(
    HttpMethod.Patch,
    "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}"
)
{
    Content = JsonContent.Create(new
    {
        permissions = new[] { 456 },
        roles = new[] { "{mailboxRoleUuid}" }
    })
};

request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer",
    "{token}"
);

using var response = await client.SendAsync(request);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request PATCH \
  "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "permissions": [456],
    "roles": ["{mailboxRoleUuid}"]
  }'
```

{% endtab %}
{% endtabs %}

Replace `456` with an actual mailbox permission ID and replace `{mailboxRoleUuid}` with the UUID of a mailbox role. A successful request returns `200 OK`.

When only a role or an individual permission is required, send an empty array for the unused property.

```json
{
  "permissions": [],
  "roles": [
    "{mailboxRoleUuid}"
  ]
}
```

### Replace all assigned permissions and roles

Use `PUT` when the request body contains the complete access configuration that the user must have. Existing permissions and roles that are not included in the request are removed.

#### Replace account access

{% tabs %}
{% tab title="Node.js" %}

```javascript
const response = await fetch(
  "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer {token}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      permissions: [123, 124],
      roles: ["{accountRoleUuid}"]
    })
  }
);
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$client = curl_init(
    "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}"
);

curl_setopt_array($client, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_POSTFIELDS => json_encode([
        "permissions" => [123, 124],
        "roles" => ["{accountRoleUuid}"]
    ]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Content-Type: application/json"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($client);
curl_close($client);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.put(
    "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}",
    headers={
        "Authorization": "Bearer {token}"
    },
    json={
        "permissions": [123, 124],
        "roles": ["{accountRoleUuid}"]
    }
)
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "json"
require "net/http"

uri = URI(
  "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}"
)
request = Net::HTTP::Put.new(
  uri,
  {
    "Authorization" => "Bearer {token}",
    "Content-Type" => "application/json"
  }
)
request.body = {
  permissions: [123, 124],
  roles: ["{accountRoleUuid}"]
}.to_json

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: uri.scheme == "https"
) { |http| http.request(request) }
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
    "bytes"
    "log"
    "net/http"
)

func main() {
    body := bytes.NewBufferString(`
{
  "permissions": [123, 124],
  "roles": ["{accountRoleUuid}"]
}`)

    request, err := http.NewRequest(
        http.MethodPut,
        "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}",
        body,
    )
    if err != nil {
        log.Fatal(err)
    }

    request.Header.Set("Authorization", "Bearer {token}")
    request.Header.Set("Content-Type", "application/json")

    response, err := http.DefaultClient.Do(request)
    if err != nil {
        log.Fatal(err)
    }
    defer response.Body.Close()
}
```

{% endtab %}

{% tab title="Java" %}

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ReplaceAccountAccess {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "permissions": [123, 124],
              "roles": ["{accountRoleUuid}"]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}"
            ))
            .header("Authorization", "Bearer {token}")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );
    }
}
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using System.Net.Http.Headers;
using System.Net.Http.Json;

using var client = new HttpClient();
using var request = new HttpRequestMessage(
    HttpMethod.Put,
    "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}"
)
{
    Content = JsonContent.Create(new
    {
        permissions = new[] { 123, 124 },
        roles = new[] { "{accountRoleUuid}" }
    })
};

request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer",
    "{token}"
);

using var response = await client.SendAsync(request);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request PUT \
  "https://{baseUrl}/api/v1/permission/{userUuid}/account/{accountUuid}" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "permissions": [123, 124],
    "roles": ["{accountRoleUuid}"]
  }'
```

{% endtab %}
{% endtabs %}

#### Replace mailbox access

{% tabs %}
{% tab title="Node.js" %}

```javascript
const response = await fetch(
  "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer {token}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      permissions: [456, 457],
      roles: ["{mailboxRoleUuid}"]
    })
  }
);
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$client = curl_init(
    "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}"
);

curl_setopt_array($client, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_POSTFIELDS => json_encode([
        "permissions" => [456, 457],
        "roles" => ["{mailboxRoleUuid}"]
    ]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Content-Type: application/json"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($client);
curl_close($client);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.put(
    "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}",
    headers={
        "Authorization": "Bearer {token}"
    },
    json={
        "permissions": [456, 457],
        "roles": ["{mailboxRoleUuid}"]
    }
)
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "json"
require "net/http"

uri = URI(
  "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}"
)
request = Net::HTTP::Put.new(
  uri,
  {
    "Authorization" => "Bearer {token}",
    "Content-Type" => "application/json"
  }
)
request.body = {
  permissions: [456, 457],
  roles: ["{mailboxRoleUuid}"]
}.to_json

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: uri.scheme == "https"
) { |http| http.request(request) }
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
    "bytes"
    "log"
    "net/http"
)

func main() {
    body := bytes.NewBufferString(`
{
  "permissions": [456, 457],
  "roles": ["{mailboxRoleUuid}"]
}`)

    request, err := http.NewRequest(
        http.MethodPut,
        "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}",
        body,
    )
    if err != nil {
        log.Fatal(err)
    }

    request.Header.Set("Authorization", "Bearer {token}")
    request.Header.Set("Content-Type", "application/json")

    response, err := http.DefaultClient.Do(request)
    if err != nil {
        log.Fatal(err)
    }
    defer response.Body.Close()
}
```

{% endtab %}

{% tab title="Java" %}

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ReplaceMailboxAccess {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "permissions": [456, 457],
              "roles": ["{mailboxRoleUuid}"]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}"
            ))
            .header("Authorization", "Bearer {token}")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );
    }
}
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using System.Net.Http.Headers;
using System.Net.Http.Json;

using var client = new HttpClient();
using var request = new HttpRequestMessage(
    HttpMethod.Put,
    "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}"
)
{
    Content = JsonContent.Create(new
    {
        permissions = new[] { 456, 457 },
        roles = new[] { "{mailboxRoleUuid}" }
    })
};

request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer",
    "{token}"
);

using var response = await client.SendAsync(request);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request PUT \
  "https://{baseUrl}/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "permissions": [456, 457],
    "roles": ["{mailboxRoleUuid}"]
  }'
```

{% endtab %}
{% endtabs %}

Both operations return `200 OK` when the replacement is successful.

{% hint style="warning" %}
Use `PATCH` to add permissions or roles while preserving existing assignments. Use `PUT` only when the request contains the complete configuration because omitted permissions and roles are removed.
{% endhint %}

### Remove an individual permission

Remove one account permission by including its numeric ID in the request path.

```http
DELETE /api/v1/permission/{userUuid}/account/{accountUuid}/{permissionId}
Authorization: Bearer {token}
```

Remove one mailbox permission through the corresponding mailbox endpoint.

```http
DELETE /api/v1/permission/{userUuid}/mailbox/{mailboxUuid}/{permissionId}
Authorization: Bearer {token}
```

A successful request returns `204 No Content` without a response body. Other permissions and roles assigned in the same context remain unchanged.

### Remove an individual role

Remove one account role by including its UUID in the request path.

```http
DELETE /api/v1/permission/{userUuid}/account/{accountUuid}/role/{roleUuid}
Authorization: Bearer {token}
```

Remove one mailbox role through the corresponding mailbox endpoint.

```http
DELETE /api/v1/permission/{userUuid}/mailbox/{mailboxUuid}/role/{roleUuid}
Authorization: Bearer {token}
```

A successful request returns `204 No Content` without a response body. Removing a role does not remove separately assigned individual permissions.

### Remove all mailbox permissions and roles

Remove the complete permission and role configuration for the user within the selected mailbox. This operation affects only the specified user-to-mailbox relation.

```http
DELETE /api/v1/permission/{userUuid}/mailbox/{mailboxUuid}
Authorization: Bearer {token}
```

A successful request returns `204 No Content` without a response body.

{% hint style="warning" %}
This operation removes every permission and role assigned to the user in the selected mailbox.
{% endhint %}

### Remove a user from an account

Remove the complete user-to-account relation when the user must no longer belong to the selected account. This operation is broader than removing one permission or role.

{% hint style="warning" %}
This operation removes the user from the account entirely. Use an individual permission or role endpoint when only part of the user's access must be revoked.
{% endhint %}

```http
DELETE /api/v1/permission/{userUuid}/account/{accountUuid}
Authorization: Bearer {token}
```

A successful request returns `204 No Content` without a response body.

### Related topics

* [Authorization](/api-reference/authorization.md)
* [Permission Roles](/guides/permission-roles.md)
* [Search Mailboxes and Contacts](/api-reference/search-mailboxes-and-contacts.md)
* [Error handling and API error codes](/error-codes/error-handling-and-api-error-codes.md)