Ключи API
Как создавать ключи API, какие у них пять областей доступа (скоупов) и как их отзывать.
Claude
ChatGPTКлюч API — учётные данные для вызовов от имени организации, не привязанные к сессии конкретного человека. Создание, список и отзыв ключей — только из кабинета (сессией, ролью владелец или администратор): сам ключ API управлять ключами не может, даже обладая всеми скоупами.
Создание ключа и скоупы
POST /v1/api_keys принимает name и необязательный список scopes — если не указать, ключ
получит все скоупы. Ключ (tz_live_…) показывается один раз, в ответе на создание — сохраните его
сразу, повторно он нигде не отображается.
Пять областей доступа (скоупов):
| Скоуп | Что разрешает |
|---|---|
typizers:read | Читать типизаторы и их версии |
typizers:write | Создавать и менять типизаторы |
runs:read | Читать прогоны, пакеты, файлы, конечные точки и доставки вебхуков |
runs:write | Запускать прогоны и пакеты, загружать файлы, управлять конечными точками вебхуков |
billing:read | Читать баланс и использование (GET /v1/usage) |
Заводите для каждого внешнего сервиса или ИИ-агента отдельный ключ с минимально нужным набором
скоупов — например, агенту, который только запускает извлечение и читает результат, достаточно
runs:write и runs:read, без typizers:write и без billing:read. Так утечка одного ключа не
даёт доступа ко всему остальному.
Отзыв ключа
DELETE /v1/api_keys/{id} отзывает ключ немедленно и необратимо — повторно создать ключ с тем же
значением нельзя, только новый. Отозванный ключ неотличим по ответу от неверного или
несуществующего — 401 unauthorized в обоих случаях.
Отключение ключей при удалении участника организации
Ключ действует, только пока участник организации, который его создал, остаётся в ней. Если автора ключа удаляют из организации (или организация его блокирует), ключ перестаёт проходить авторизацию — автоматически, без отдельного отзыва. Это стоит учитывать, увольняя сотрудника или отзывая доступ подрядчика: удаление из организации само по себе отключает все ключи, которые он создавал.
Что дальше
- «Первый вызов API» — использование ключа в запросе.
- «Подключение через MCP» — тот же ключ как
Authorization: Bearerдля MCP-сервера. - «Обработка ошибок и повторов» — что означает
401 unauthorizedи403 insufficient_scope.