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

Method	Endpoint	Purpose
GET	/api/v1/permission/{userUuid}/account/{accountUuid}	Retrieve account permissions and roles
PATCH	/api/v1/permission/{userUuid}/account/{accountUuid}	Add account permissions and roles
PUT	/api/v1/permission/{userUuid}/account/{accountUuid}	Replace account permissions and roles
DELETE	/api/v1/permission/{userUuid}/account/{accountUuid}/{permissionId}	Remove one account permission
DELETE	/api/v1/permission/{userUuid}/account/{accountUuid}/role/{roleUuid}	Remove one account role
DELETE	/api/v1/permission/{userUuid}/account/{accountUuid}	Remove the user from the account

Mailbox permissions

Method	Endpoint	Purpose
PATCH	/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}	Add mailbox permissions and roles
PUT	/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}	Replace mailbox permissions and roles
DELETE	/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}/{permissionId}	Remove one mailbox permission
DELETE	/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}/role/{roleUuid}	Remove one mailbox role
DELETE	/api/v1/permission/{userUuid}/mailbox/{mailboxUuid}	Remove all mailbox permissions and roles

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.

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

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

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

Use permission IDs and role UUIDs returned by the Permission Roles 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.

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

A successful request returns 200 OK.

Node.js

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);

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;

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())

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

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))
}

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());
  }
}

.NET

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);

cURL

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

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.

Node.js

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}"]
    })
  }
);

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);

Python

import requests

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

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) }

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()
}

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()
        );
    }
}

.NET

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);

cURL

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}"]
  }'

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.

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.

Node.js

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}"]
    })
  }
);

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);

Python

import requests

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

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) }

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()
}

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()
        );
    }
}

.NET

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);

cURL

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}"]
  }'

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.

{
  "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

Node.js

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}"]
    })
  }
);

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);

Python

import requests

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

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) }

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()
}

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()
        );
    }
}

.NET

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);

cURL

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}"]
  }'

Replace mailbox access

Node.js

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}"]
    })
  }
);

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);

Python

import requests

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

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) }

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()
}

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()
        );
    }
}

.NET

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);

cURL

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}"]
  }'

Both operations return 200 OK when the replacement is successful.

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.

Remove an individual permission

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

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

Remove one mailbox permission through the corresponding mailbox endpoint.

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.

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

Remove one mailbox role through the corresponding mailbox endpoint.

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.

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

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

This operation removes every permission and role assigned to the user in the selected mailbox.

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.

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.

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

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

Related topics

• Authorization

• Permission Roles

• Search Mailboxes and Contacts

• Error handling and API error codes