Создание и управление токенами API

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

Подключаете клиент MCP? Если он поддерживает авторизацию в браузере, добавьте https://trekmail.net/mcp в качестве удаленного сервера MCP и подтвердите доступ в браузере. Обычно создавать или вставлять токен не требуется. Ручные токены tm_live_ предназначены для скриптов, заданий CI, самостоятельно размещенного MCP и клиентов без поддержки этого процесса. См. Подключение ИИ-агентов (MCP).

Перед началом

• Все тарифы, включая Nano, позволяют создавать токены API. Тарифы Nano ограничены областями Email Verifier (verify:read, verify:write).
• Тарифы Starter предоставляют области инфраструктуры только для чтения, а также полный набор областей Drive и Email Verifier. Starter также позволяет управлять пересылкой на панели, но доступ на запись для пересылки через API (mailboxes:forwarding:write) требует Pro или Agency. Pro и Agency открывают все области.
• Владелец может управлять всеми учетными данными аккаунта. Делегированный участник с разрешением на токены API может управлять только созданными им учетными данными и предоставлять только те области и домены, которые уже входят в его членство.
• Совет: Нажмите Начать обзор на странице «ИИ-агенты и API», чтобы быстро ознакомиться с вариантами подключения, токенами, подключенными приложениями и журналом аудита.

Создание токена автоматизации Drive

API Drive и инструменты MCP используют операционные токены (tm_live_...). Выбирайте только те области Drive, которые нужны рабочему процессу:

• Отчеты только для чтения: drive:account:read, drive:mailbox:read или drive:addon:read.
• Автоматическая загрузка: добавьте drive:account:write или drive:mailbox:write.
• Общедоступные ссылки доставки: добавьте drive:account:share или drive:mailbox:share.
• Безвозвратная очистка: используйте drive:account:purge или drive:mailbox:purge только в отдельном токене со строгим контролем.

Покупка, изменение размера и отмена дополнения Drive недоступны через токены API. Агенты могут читать состояние и цены дополнения с областью drive:addon:read, но изменения подписки выполняются на панели.

Создание токена автоматизации White Label

White Label использует пять областей операционного токена: branding:read, branding:write, members:read, members:write и activity:read. Они отображаются, только пока учетная запись имеет доступ к White Label. Область members:write помечена как опасная, поскольку позволяет удалить доступ и отозвать ключи другого человека.

Для интеграции состояния и аудита только для чтения выберите branding:read, members:read и activity:read. Добавляйте branding:write только для настройки бренда и DNS. Добавляйте members:write, только если автоматизация должна приглашать или изменять участников.

В течение льготного периода отмены владелец сохраняет три области чтения для восстановления, а операции записи и делегированные учетные данные White Label перестают работать. Повторная активация не восстанавливает отозванные учетные данные; создайте или авторизуйте новые.

Создание токена

1. Откройте ИИ-агенты и API → Токены.
2. Нажмите Создать токен.
3. Заполните форму:
   • Имя: Метка для идентификации токена (например, «Агент Claude», «Конвейер CI/CD»).
   • Срок действия: Выберите 7 дней, 30 дней, 90 дней, свою дату или вариант без срока.
   • Области: Выберите операции, которые сможет выполнять токен. По умолчанию отмечены все разрешенные области.
   • Ограничение домена: Выберите «Все домены» или конкретные домены, чтобы ограничить доступ токена.
4. Нажмите Создать токен.

После создания токен в открытом виде отображается один раз. Немедленно скопируйте его или сохраните как файл .txt кнопкой Скачать.

Повторно просмотреть токен невозможно. Надежно сохраните его до закрытия подтверждения.

Создание токена сообщений

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

Чтобы создать токен сообщений, агент вызывает:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

Выберите минимальные области, необходимые рабочему процессу:

Токен в открытом виде (tm_msg_...) возвращается один раз. Добавьте его в конфигурацию MCP как TREKMAIL_MESSAGE_TOKEN.

Токены сообщений доступны на тарифах Pro и Agency. Операционный токен должен иметь область mailboxes:message-tokens:manage.

Для подключенного Gmail или другого внешнего ящика используйте external_account_id. Чтобы получатели вместо него видели авторизованный рабочий адрес, также используйте identity_id, возвращенный endpoint личностей. См. Адреса «От имени» через API и MCP.

Формат токена

TrekMail использует два префикса для различения типов токенов:

Первые 8 символов после префикса сохраняются как видимый префикс на панели для удобной идентификации.

Области доступа

Области определяют, что может делать токен. Доступные варианты зависят от вашего тарифа:

• Nano: Только Email Verifier (verify:read, verify:write). При добавлении Drive Storage учетная запись также получает положенные ей возможности API Drive и MCP.
• Starter: Полный доступ к Drive и Email Verifier и доступ только для чтения ко всему остальному (домены, ящики, пересылка, фильтры почты, автоответ, миграции, обращения, SMTP, Cloudflare). Используйте панель для операций записи, которые Starter не предоставляет через API, например для создания миграций, ответов на обращения или изменения автоответа.
• Pro и Agency: Полный доступ. Чтение, запись, создание и удаление во всех семействах, а также токены сообщений для чтения и отправки почты через API.

Области White Label предоставляются как право дополнения, а не как способ обойти таблицу тарифов. Они предлагаются, только когда White Label активен; владелец сохраняет доступ только для чтения в целях восстановления в течение льготного периода отмены.

Описание каждой области приведено в статье Области API и разрешения тарифов.

Ограничения доменов

По умолчанию токены могут обращаться ко всем доменам вашей учетной записи. Чтобы ограничить токен конкретными доменами:

1. Выберите Выбранные домены в разделе ограничений доменов.
2. Отметьте домены, к которым должен обращаться токен.

Ограниченный токен получает ответы 404 при попытке обратиться к ресурсам других доменов; API ведет себя так, будто этих доменов не существует.

Отзыв токена

1. Откройте ИИ-агенты и API → Токены.
2. Найдите токен в списке.
3. Нажмите Отозвать.
4. Подтвердите отзыв.

Отозванные токены немедленно прекращают работать. Любой запрос API с отозванным токеном получает 401 Unauthorized.

Отзыв необратим. Если нужно восстановить доступ, создайте новый токен.

Состояние токена

У токенов есть три состояния:

Используйте фильтр состояния на странице токенов, чтобы просматривать токены по состоянию.

Журнал аудита

Каждое создание и отзыв токена отображается на вкладке Журнал аудита. События содержат имя токена, действие и время.

Быстрые решения

• «Области недоступны на вашем тарифе»: Тариф не включает эти области. Nano ограничен verify:read и verify:write (добавьте дополнение Drive Storage, чтобы также получить области drive:*). Starter добавляет чтение всех семейств инфраструктуры, а также полный доступ к Drive и Email Verifier. Pro и Agency открывают запись во всех разделах.
• Утерян токен в открытом виде: Восстановить токен невозможно. Отзовите его и создайте новый.
• Токен работает, но возвращает 404 для некоторых доменов: Вероятно, на токене установлено ограничение домена. Отзовите и создайте его заново с вариантом «Все домены» либо добавьте отсутствующие домены в ограничение.
• Область White Label возвращает scope_blocked_by_entitlement: Снова активируйте White Label, затем создайте или авторизуйте учетные данные с нужной областью.
• Делегированный токен перестал работать после изменения роли: Сокращение, приостановка или удаление доступа участника немедленно отзывает затронутые учетные данные. Создайте новый токен после того, как владелец восстановит правильный доступ.

Связанные статьи

• Обзор API Drive
• Обзор API
• Области API и разрешения тарифов
• Подключение ИИ-агентов (MCP)
• Управление командами White Label через API и MCP