Skip to navigation
Основные понятия

Разрешения

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

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

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

Так вы получаете точный контроль над ресурсами и операциями для каждого ключа — поверх уже существующей изоляции по области для ключей с областью pod и ключей с областью inbox.

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

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

При создании 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

Если разрешение на видимость метки запрещено, элементы с этой меткой автоматически исключаются из списков и при прямом обращении возвращается «не найдено». Например, при 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-ключ, который может читать все ресурсы, но не создавать, не обновлять и не удалять.

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)

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

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

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

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

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

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

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

  • Принцип минимальных привилегий. Выдавайте только те права, которые реально нужны агенту. Саппорт-агенту, который читает и отвечает на письма, не нужны domain_create или inbox_delete.
  • Сочетайте с областями для защиты в глубину. Используйте вместе с ключами с областью pod или ключами с областью inbox. Область ограничивает какие ресурсы видит ключ, а разрешения — что он может с ними делать.
  • Отсекайте нежелательный контент для агентов. Для ключей агентов ставьте label_spam_read, label_blocked_read и label_trash_read в false, чтобы агенты не видели и не обрабатывали ненужную почту и сохраняли чистый контекст.