API-ключи

API-ключ — единственный способ аутентификации в Public API. JWT и cookie дашборда здесь не работают.

Authorization: Bearer mi_live_ab12cd34ef56gh78ij90kl12mn34op56

Ключ привязан к конкретному проекту и определяет, от чьего имени и в какой среде выполняется запрос. Создание, ротация и отзыв ключей — в дашборде: Проект → API-ключи.

Plain-токен показывается один раз

При создании дашборд один раз отдаёт полное значение ключа. Сохраните его сразу — потом видна только префикс-часть (mi_live_ab12cd…).

Окружение: LIVE и TEST

Окружение зашито в префикс ключа.

	mi_live_… (LIVE)	mi_test_… (TEST / sandbox)
Реальная отправка	да	нет, статус SIMULATED
Нужен верифицированный домен	да	нет
Подписанный DPA	да	нет
Месячный объём	применяется	не расходуется

TEST удобен для CI и интеграционных тестов: тот же endpoint, та же схема ответа, но письма только сохраняются со статусом SIMULATED и не доставляются получателям. Защитные ограничения размера запроса, числа получателей и вложений сохраняются.

Не путайте TEST-ключ с одноразовым onboarding trial через адрес *@sandbox.mailinfra.ru и LIVE-ключ. Такой trial разрешает одно реальное письмо только на email создателя ключа и не поддерживает resend. Для многократных тестов используйте mi_test_….

Права доступа

Право	POST /v1/emails POST /v1/emails/batch	GET /v1/emails GET /v1/emails/{id} GET /v1/emails/{id}/events
FULL_ACCESS	да	да
SENDING_ONLY	да	нет
READ_ONLY	нет	да

Запрос с недостаточными правами возвращает 403 Forbidden — ключ остаётся валидным, отзывать его не нужно.

Типичные сценарии:

• SENDING_ONLY — backend-сервис, который только шлёт транзакционные письма и не должен иметь доступ к содержимому логов.
• READ_ONLY — внутренние BI-дашборды, скрипты сверки, инциденты.
• FULL_ACCESS — небольшие приложения, которым удобно делать оба класса операций одним ключом.

Срок действия и отзыв

• expires_at (опционально) — после этой даты запросы возвращают 401 Unauthorized. По умолчанию ключ бессрочный.
• Отзыв ключа в дашборде применяется немедленно: следующий запрос с этим ключом получит 401.

Хранение и ротация

Храните ключ как пароль — в переменных окружения или секретах CI, не в репозитории.

Python

import os
api_key = os.environ["MAILINFRA_API_KEY"]

TypeScript / Node.js

const apiKey = process.env.MAILINFRA_API_KEY!;

Go

apiKey := os.Getenv("MAILINFRA_API_KEY")

При утечке или плановой смене:

1. Создайте новый ключ в дашборде.
2. Обновите секрет в окружении приложения.
3. Отзовите старый ключ.

Ошибки аутентификации

HTTP	Когда возникает
401 Unauthorized	Ключ отсутствует, неверный, отозван или истёк
403 Forbidden	Ключ валиден, но прав недостаточно для этого endpoint

---

Управление ключами через API

Создавать, листать и отзывать ключи можно не только в дашборде, но и программно. Эти эндпоинты — часть Management API: они идут не с mi_live_… ключом, а с сессионным токеном пользователя.

Базовый префикс: /v1/organizations/{organization_id}/projects/{project_id}/api-keys.

Создать ключ

POST /v1/organizations/{organization_id}/projects/{project_id}/api-keys
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "name": "Backend production",
  "permissions": "FULL_ACCESS",
  "env": "LIVE",
  "expires_at": null
}

Поле	Тип	По умолчанию	Описание
name	string	—	1–100 символов; уникален среди активных ключей проекта
permissions	FULL_ACCESS | SENDING_ONLY | READ_ONLY	FULL_ACCESS	См. таблицу прав выше
env	LIVE | TEST	LIVE	Окружение
expires_at	datetime | null	null	ISO-8601, UTC; null — бессрочный

Ответ 201 Created содержит key — plain-токен, показывается только в этом ответе:

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "project_id": "...",
    "name": "Backend production",
    "prefix": "mi_live_ab12cd",
    "permissions": "FULL_ACCESS",
    "env": "LIVE",
    "last_used_at": null,
    "expires_at": null,
    "revoked_at": null,
    "created_at": "2026-05-12T09:00:00Z",
    "key": "mi_live_ab12cd34ef56gh78ij90kl12mn34op56qr78st90uv12wx34yz56"
  }
}

Список ключей

GET /v1/organizations/{organization_id}/projects/{project_id}/api-keys
Authorization: Bearer <session_token>

Параметр ?include_revoked=true дополнительно возвращает отозванные ключи. По умолчанию отозванные скрыты. Поле key в листинге не возвращается — видна только префикс-часть (prefix) для опознавания.

Отозвать ключ

DELETE /v1/organizations/{organization_id}/projects/{project_id}/api-keys/{key_id}
Authorization: Bearer <session_token>

После этого следующий запрос с этим ключом получит 401. Имя отозванного ключа можно переиспользовать — уникальность держится только среди активных.

Возможные ошибки

HTTP	Код	Когда
409	conflict	Активный ключ с таким именем уже существует в проекте
404	not_found	Проект не найден или не принадлежит организации
403	forbidden	У пользователя меньше прав, чем DEVELOPER в организации