API-ключи

GET /keys перечисляет каждый ключ, который видит вызывающий, новые сначала и по одной странице, с его статусом, скоупами, ролью, областью отправки, временем последнего использования и тем, кто его создал и последним менял. GET /keys/{id} читает один. Ни одно чтение не возвращает секрет: maskedKey достаточно, чтобы различить два ключа. Оба требуют keys:read.

{  "object": "api_key",  "id": "4c1b257a66287fd113bd89d0",  "name": "Billing sender",  "maskedKey": "oe_live_4c1b…kX7a",  "status": "active",  "scopes": ["emails:send"],  "roleId": null,  "domainAllowlist": ["billing.acme.com"],  "expiresAt": "2026-12-22T09:00:00.000Z",  "lastUsedAt": "2026-09-23T08:14:02.000Z",  "createdBy": { "kind": "apiKey", "name": "API key Provisioner", "label": "API key Provisioner" }}

• —POST /keys создаёт ключ и возвращает его секрет в token, один раз. Если не указаны, скоуп будет emails:send, а роль, область отправки и срок действия будут как у вызывающего.
• —PATCH /keys/{id} переименовывает ключ, заменяет его скоупы или область отправки и выключает и включает его через enabled. Выключение обратимо: ключ сохраняет всё и отклоняется с inactive_api_key, пока его снова не включат.
• —POST /keys/{id}/rotate даёт ключу новый секрет и возвращает его один раз. Старый секрет перестаёт работать в тот момент, когда вызов возвращается.
• —POST /keys/{id}/revoke навсегда выводит ключ из работы, с необязательным reason. DELETE /keys/{id} затем убирает его из списка и сохраняет историю.
• —Каждому из них нужен keys:manage. Ротация самого вызывающего ключа работает и с keys:write, ровно как POST /keys/self/rotate.

Каждое изменение проверяется по ключу, который его делает. Ключ, который по любой оси оказался бы за пределами вызывающего, отклоняется с 403 beyond_caller_authority, а param называет ось:

• —Скоупы: только те, что есть у вызывающего после того, как его собственная роль их сузила.
• —Роль: вызывающий, ограниченный ролью, может создавать ключи и управлять только ключами с той же ролью.
• —Срок действия: вызывающий со сроком действия может создавать ключи и управлять только ключами, которые истекают не позже.
• —Режим: тестовый ключ достаёт только до тестовых ключей.
• —Область отправки: только домены и адреса внутри области вызывающего, и один адрес никогда не покрывает весь свой домен.

Консоль просит подтвердить себя ещё раз, прежде чем создать или ротировать ключ. У вызова, сделанного ключом, этого не попросить, поэтому keys:manage это доступ, который создаёт доступы: утёкший ключ с ним может создать собственные ключи, в пределах своего охвата, которые продолжат работать после его отзыва.

• —Давайте keys:manage только автоматизации, чья работа выпускать ключи, и никогда ключу, который отправляет почту.
• —Сузьте этот ключ: роль, область отправки и срок действия. Всё, что он создаёт, наследует все три и никогда их не превысит.
• —Следите за GET /keys/activity. Каждый ключ, который он создаёт, меняет или отзывает, записывается на него по имени, так что утечка видна как ключи, которых вы не ждали.
• —keys:read открывает журнал запросов, включая IP-адреса и user agent. Относитесь к нему как к доступу для аудита.

GET /keys/requests и GET /keys/{id}/requests читают каждый аутентифицированный вызов ключа, новые сначала: метод, путь, статус, код ошибки, длительность, IP и user agent, никогда тело или строку запроса. keyIds, failedOnly, since и until это фильтры из консоли. GET /keys/activity и GET /keys/{id}/activity читают, что происходило с ключами, а actor называет, кто это сделал, как @username или API key <name>. Ничего не удаляется, и удалённый ключ сохраняет историю.