> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://agentinbox.space/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://agentinbox.space/_mcp/server.

# Разрешения

> Узнайте, как настраивать тонкие разрешения на API-ключах, чтобы ограничить доступ к конкретным ресурсам и операциям.

## Что такое разрешения?

`Permissions` позволяют ограничить, что может делать API-ключ. По умолчанию ключ имеет полный доступ в пределах своей области (организация, pod или inbox). Если вы передаёте объект `permissions`, он работает как **белый список**: разрешены только те права, которые явно установлены в `true`. Всё остальное запрещено.

Так вы получаете точный контроль над ресурсами и операциями для каждого ключа — поверх уже существующей изоляции по области для [ключей с областью pod](/pods) и [ключей с областью inbox](/inboxes#inbox-scoped-api-keys).

## Как работают разрешения

### Модель белого списка

При создании API-ключа с объектом `permissions` режим переключается с «полного доступа» на «белый список»:

* **Без поля `permissions`**: ключ имеет полный доступ в пределах своей области. Это поведение по умолчанию и обратно совместимо с уже существующими ключами.
* **Если `permissions` указан**: разрешены только права, выставленные в `true`. Любое право, которое опущено или равно `false`, запрещено.

> **Обратная совместимость**
>
> У существующих API-ключей без поля `permissions` всё работает как раньше — полный доступ. Белый список включается только когда вы явно передаёте объект `permissions`.

### Пересечение с областью (scope)

Разрешения пересекаются с областью ключа. Ключ, ограниченный одним inbox, не получит возможностей уровня организации (например `inbox_create` или `domain_create`), даже если в `permissions` они `true`. Эффективные права — это пересечение того, что допускает область, и того, что даёт объект `permissions`.

### Защита от повышения привилегий

Ограниченный API-ключ не может создать дочерний ключ с большими правами, чем у него самого. При создании нового ключа права потомка автоматически ограничиваются эффективными правами родителя. Так нельзя повысить привилегии через создание ключей.

## Справочник разрешений

### Inbox

| Разрешение     | Описание                  |
| -------------- | ------------------------- |
| `inbox_read`   | Чтение параметров inbox   |
| `inbox_create` | Создание новых inbox      |
| `inbox_update` | Обновление настроек inbox |
| `inbox_delete` | Удаление inbox            |

### Треды (Threads)

| Разрешение      | Описание        |
| --------------- | --------------- |
| `thread_read`   | Чтение тредов   |
| `thread_delete` | Удаление тредов |

### Сообщения (Messages)

| Разрешение       | Описание                   |
| ---------------- | -------------------------- |
| `message_read`   | Чтение сообщений           |
| `message_send`   | Отправка сообщений         |
| `message_update` | Обновление меток сообщений |

### Видимость меток (Label visibility)

| Разрешение           | Описание                             |
| -------------------- | ------------------------------------ |
| `label_spam_read`    | Доступ к сообщениям с меткой spam    |
| `label_blocked_read` | Доступ к сообщениям с меткой blocked |
| `label_trash_read`   | Доступ к сообщениям с меткой trash   |

> **Info**
>
> Если разрешение на видимость метки запрещено, элементы с этой меткой автоматически исключаются из списков и при прямом обращении возвращается «не найдено». Например, при `label_spam_read: false` ключ никогда не увидит спам ни в списках, ни при поиске.

### Черновики (Drafts)

| Разрешение     | Описание              |
| -------------- | --------------------- |
| `draft_read`   | Чтение черновиков     |
| `draft_create` | Создание черновиков   |
| `draft_update` | Обновление черновиков |
| `draft_delete` | Удаление черновиков   |
| `draft_send`   | Отправка черновиков   |

### Вебхуки (Webhooks)

| Разрешение       | Описание                     |
| ---------------- | ---------------------------- |
| `webhook_read`   | Чтение конфигураций вебхуков |
| `webhook_create` | Создание вебхуков            |
| `webhook_update` | Обновление вебхуков          |
| `webhook_delete` | Удаление вебхуков            |

### Домены (Domains)

| Разрешение      | Описание                 |
| --------------- | ------------------------ |
| `domain_read`   | Чтение сведений о домене |
| `domain_create` | Создание доменов         |
| `domain_update` | Обновление доменов       |
| `domain_delete` | Удаление доменов         |

### Списки (Lists)

| Разрешение          | Описание                |
| ------------------- | ----------------------- |
| `list_entry_read`   | Чтение записей списка   |
| `list_entry_create` | Создание записей списка |
| `list_entry_delete` | Удаление записей списка |

### Метрики (Metrics)

| Разрешение     | Описание      |
| -------------- | ------------- |
| `metrics_read` | Чтение метрик |

### API-ключи

| Разрешение       | Описание            |
| ---------------- | ------------------- |
| `api_key_read`   | Чтение API-ключей   |
| `api_key_create` | Создание API-ключей |
| `api_key_delete` | Удаление API-ключей |

### Pod

| Разрешение   | Описание     |
| ------------ | ------------ |
| `pod_read`   | Чтение pod   |
| `pod_create` | Создание pod |
| `pod_delete` | Удаление pod |

## Примеры кода

### Ключ только на чтение

Создайте API-ключ, который может читать все ресурсы, но не создавать, не обновлять и не удалять.

**`Python`**

```python title="Python"
from agentinbox import Agentinbox

client = Agentinbox(api_key="YOUR_API_KEY")

key = client.api_keys.create(
    name="read-only-agent",
    permissions={
        "inbox_read": True,
        "thread_read": True,
        "message_read": True,
        "draft_read": True,
        "webhook_read": True,
        "domain_read": True,
        "list_entry_read": True,
        "metrics_read": True,
        "api_key_read": True,
        "pod_read": True,
        "label_spam_read": True,
        "label_blocked_read": True,
        "label_trash_read": True,
    }
)

print(key.api_key)
```

**`TypeScript`**

```typescript title="TypeScript"
import { AgentinboxClient } from "agentinbox";

const client = new AgentinboxClient({ apiKey: "YOUR_API_KEY" });

const key = await client.apiKeys.create({
  name: "read-only-agent",
  permissions: {
    inboxRead: true,
    threadRead: true,
    messageRead: true,
    draftRead: true,
    webhookRead: true,
    domainRead: true,
    listEntryRead: true,
    metricsRead: true,
    apiKeyRead: true,
    podRead: true,
    labelSpamRead: true,
    labelBlockedRead: true,
    labelTrashRead: true,
  },
});

console.log(key.apiKey);
```

**`CLI`**

```bash title="CLI"
# создать API-ключ только на чтение
agentinbox api-keys create \
  --name "read-only-agent" \
  --permissions '{
    "inbox_read": true,
    "thread_read": true,
    "message_read": true,
    "draft_read": true,
    "webhook_read": true,
    "domain_read": true,
    "list_entry_read": true,
    "metrics_read": true,
    "api_key_read": true,
    "pod_read": true,
    "label_spam_read": true,
    "label_blocked_read": true,
    "label_trash_read": true
  }'
```

### Ключ без спама

Создайте ключ с полным доступом, но без видимости контента в spam, blocked и trash. Удобно для ключей агентов, чтобы они не обрабатывали нежелательную почту.

**`Python`**

```python title="Python"
key = client.api_keys.create(
    name="clean-inbox-agent",
    permissions={
        "inbox_read": True,
        "inbox_create": True,
        "inbox_update": True,
        "inbox_delete": True,
        "thread_read": True,
        "thread_delete": True,
        "message_read": True,
        "message_send": True,
        "message_update": True,
        "label_spam_read": False,
        "label_blocked_read": False,
        "label_trash_read": False,
        "draft_read": True,
        "draft_create": True,
        "draft_update": True,
        "draft_delete": True,
        "draft_send": True,
        "webhook_read": True,
        "webhook_create": True,
        "webhook_update": True,
        "webhook_delete": True,
        "domain_read": True,
        "domain_create": True,
        "domain_update": True,
        "domain_delete": True,
        "list_entry_read": True,
        "list_entry_create": True,
        "list_entry_delete": True,
        "metrics_read": True,
        "api_key_read": True,
        "api_key_create": True,
        "api_key_delete": True,
        "pod_read": True,
        "pod_create": True,
        "pod_delete": True,
    }
)
```

**`TypeScript`**

```typescript title="TypeScript"
const key = await client.apiKeys.create({
  name: "clean-inbox-agent",
  permissions: {
    inboxRead: true,
    inboxCreate: true,
    inboxUpdate: true,
    inboxDelete: true,
    threadRead: true,
    threadDelete: true,
    messageRead: true,
    messageSend: true,
    messageUpdate: true,
    labelSpamRead: false,
    labelBlockedRead: false,
    labelTrashRead: false,
    draftRead: true,
    draftCreate: true,
    draftUpdate: true,
    draftDelete: true,
    draftSend: true,
    webhookRead: true,
    webhookCreate: true,
    webhookUpdate: true,
    webhookDelete: true,
    domainRead: true,
    domainCreate: true,
    domainUpdate: true,
    domainDelete: true,
    listEntryRead: true,
    listEntryCreate: true,
    listEntryDelete: true,
    metricsRead: true,
    apiKeyRead: true,
    apiKeyCreate: true,
    apiKeyDelete: true,
    podRead: true,
    podCreate: true,
    podDelete: true,
  },
});
```

**`CLI`**

```bash title="CLI"
# ключ с полным доступом, но без видимости spam/blocked/trash
agentinbox api-keys create \
  --name "clean-inbox-agent" \
  --permissions '{
    "inbox_read": true,
    "inbox_create": true,
    "inbox_update": true,
    "inbox_delete": true,
    "thread_read": true,
    "thread_delete": true,
    "message_read": true,
    "message_send": true,
    "message_update": true,
    "label_spam_read": false,
    "label_blocked_read": false,
    "label_trash_read": false,
    "draft_read": true,
    "draft_create": true,
    "draft_update": true,
    "draft_delete": true,
    "draft_send": true,
    "webhook_read": true,
    "webhook_create": true,
    "webhook_update": true,
    "webhook_delete": true,
    "domain_read": true,
    "domain_create": true,
    "domain_update": true,
    "domain_delete": true,
    "list_entry_read": true,
    "list_entry_create": true,
    "list_entry_delete": true,
    "metrics_read": true,
    "api_key_read": true,
    "api_key_create": true,
    "api_key_delete": true,
    "pod_read": true,
    "pod_create": true,
    "pod_delete": true
  }'
```

## Скопировать в Cursor / Claude

Скопируйте один из блоков ниже в Cursor или Claude, чтобы дать полный контекст по API разрешений за один раз.

**`Python`**

```python title="Python"
"""
Agent Inbox Permissions — copy into Cursor/Claude.

Permissions are a whitelist on API keys. No `permissions` field = full access.
When `permissions` is set, only `True` values are granted; omitted or `False` = denied.
Permissions intersect with scope (pod/inbox). A restricted key cannot create a more privileged child key.

Permission fields (all optional<bool>, resource_action format):
  Inboxes: inbox_read, inbox_create, inbox_update, inbox_delete
  Threads: thread_read, thread_delete
  Messages: message_read, message_send, message_update
  Label visibility: label_spam_read, label_blocked_read, label_trash_read
  Drafts: draft_read, draft_create, draft_update, draft_delete, draft_send
  Webhooks: webhook_read, webhook_create, webhook_update, webhook_delete
  Domains: domain_read, domain_create, domain_update, domain_delete
  Lists: list_entry_read, list_entry_create, list_entry_delete
  Metrics: metrics_read
  API Keys: api_key_read, api_key_create, api_key_delete
  Pods: pod_read, pod_create, pod_delete

API: api_keys.create(name, permissions={...})
"""
from agentinbox import Agentinbox

client = Agentinbox(api_key="YOUR_API_KEY")

# read-only key
key = client.api_keys.create(
    name="read-only",
    permissions={"inbox_read": True, "message_read": True, "thread_read": True}
)
print(key.api_key)
```

**`TypeScript`**

```typescript title="TypeScript"
/**
 * Agent Inbox Permissions — copy into Cursor/Claude.
 *
 * Permissions are a whitelist on API keys. No `permissions` field = full access.
 * When `permissions` is set, only `true` values are granted; omitted or `false` = denied.
 * Permissions intersect with scope (pod/inbox). A restricted key cannot create a more privileged child key.
 *
 * Permission fields (all optional boolean, resourceAction format):
 *   Inboxes: inboxRead, inboxCreate, inboxUpdate, inboxDelete
 *   Threads: threadRead, threadDelete
 *   Messages: messageRead, messageSend, messageUpdate
 *   Label visibility: labelSpamRead, labelBlockedRead, labelTrashRead
 *   Drafts: draftRead, draftCreate, draftUpdate, draftDelete, draftSend
 *   Webhooks: webhookRead, webhookCreate, webhookUpdate, webhookDelete
 *   Domains: domainRead, domainCreate, domainUpdate, domainDelete
 *   Lists: listEntryRead, listEntryCreate, listEntryDelete
 *   Metrics: metricsRead
 *   API Keys: apiKeyRead, apiKeyCreate, apiKeyDelete
 *   Pods: podRead, podCreate, podDelete
 *
 * API: apiKeys.create({ name, permissions: {...} })
 */
import { AgentinboxClient } from "agentinbox";

const client = new AgentinboxClient({ apiKey: "YOUR_API_KEY" });

async function main() {
  // read-only key
  const key = await client.apiKeys.create({
    name: "read-only",
    permissions: { inboxRead: true, messageRead: true, threadRead: true },
  });
  console.log(key.apiKey);
}
main();
```

## Рекомендации

* **Принцип минимальных привилегий.** Выдавайте только те права, которые реально нужны агенту. Саппорт-агенту, который читает и отвечает на письма, не нужны `domain_create` или `inbox_delete`.
* **Сочетайте с областями для защиты в глубину.** Используйте вместе с [ключами с областью pod](/multi-tenancy#pod-scoped-keys) или [ключами с областью inbox](/multi-tenancy#inbox-scoped-keys). Область ограничивает *какие* ресурсы видит ключ, а разрешения — *что* он может с ними делать.
* **Отсекайте нежелательный контент для агентов.** Для ключей агентов ставьте `label_spam_read`, `label_blocked_read` и `label_trash_read` в `false`, чтобы агенты не видели и не обрабатывали ненужную почту и сохраняли чистый контекст.