База знаний
API-ключи
Ключ на каждую задачу, только с нужными правами и отправителями, и каждый вызов в журнале.
Подробности
- Создаются в разделе Настройки → API-ключи, в рабочем пространстве, которым вы владеете. Секрет показывается один раз, и каждый ключ является ключом oe_live_.
- Ключ содержит только выбранные права, новый начинается с emails:send. Он может нести и роль, которая служит потолком, а не второй выдачей прав: GET /ping возвращает права, указанные в ключе, и права, оставленные ролью, так что у 403 на право, которое у ключа явно есть, видна причина.
- Область отправки включает до 25 целых доменов и 50 отдельных адресов. Целый домен покрывает и адреса, добавленные позже, а отправитель вне списка получает отказ 403.
- Необязательный срок действия позволяет ключу истечь самому, до десяти лет вперёд.
- Замена меняет только секрет: id, права, область отправки и история запросов сохраняются, а старый секрет перестаёт работать в момент создания нового. Ключ с правом keys:write может заменить себя сам через API. Отзыв это обновление, а не удаление, поэтому следующий вызов получит revoked_api_key.
- Каждый аутентифицированный вызов записывается с методом, путём, статусом, кодом ошибки, длительностью, IP и user agent, но никогда с телом или строкой запроса. Страница ключа показывает это во вкладках «Аналитика», «Активность» и «Запросы»: самые нагруженные маршруты, как часто они падают и их медианная задержка, а те же виды охватывают сразу несколько ключей. Журнал хранится, а не подрезается.
- Всё, что умеет страница, есть и в API, и в SDK: GET /keys и GET /keys/{id} читают ключи без их секретов, POST /keys создаёт ключ, PATCH /keys/{id} переименовывает его, меняет скоупы или область отправки, выключает и снова включает, а rotate, revoke и delete делают то, что написано. Журнал запросов и активность читаются так же, по одному ключу или по всем, с фильтрами страницы. Чтение требует keys:read, а любое изменение keys:manage: два скоупа, которых нет ни у одного ключа, пока их кто-то не выдал. MCP-сервер тоже читает журнал и активность, это listApiKeyRequests и listApiKeyActivity.
- Ключ никогда не создаёт и не достаёт ключ шире себя: скоупы, роль, срок действия, режим и область отправки должны лежать внутри ключа, который делает вызов. Повторное подтверждение нельзя применить к вызову, сделанному ключом, поэтому keys:manage это доступ, который создаёт доступы. Давайте его только автоматизации, выпускающей ключи, со своей ролью, областью отправки и сроком действия, и следите за вкладкой «Активность», где всё, что она делает, записано на неё.
- Чего нет: ключ нельзя привязать к IP-адресам, и ключ тестового режима создать нельзя.