API-ключи: области действия, срок жизни, отзыв
Все запросы к sandbox-api.k8s.tangovision.dev аутентифицируются org-scoped bearer-токеном tvk_…. Ключи выпускаются в портале разработчика; открытый текст показывается ровно один раз. Эта страница — справочник по поведению ключей.
Сначала два инварианта:
- Ключ никогда не может выпустить другой ключ. Для выпуска нужна активная сессия портала, поэтому утёкший ключ не размножится.
- До 5 активных ключей на организацию. Отозванные и истёкшие ключи не считаются — отзывайте то, чем не пользуетесь.
Области действия
Каждый ключ несёт одну область действия, выбранную при выпуске:
| Область | Разрешает | Для чего |
|---|---|---|
sandbox (по умолчанию) | API жизненного цикла песочниц (/api/v1/sandboxes*): создание, список, продление, сброс, удаление | Повседневная разработка модулей, CI, создающий песочницы |
publish | Публикация модулей (появится вместе с tv-sdk publish; пока ни один эндпоинт её не принимает) | Релизные конвейеры — когда публикация выйдет |
full | Всё вышеперечисленное плюс список и отзыв ключей через API | Аварийная автоматизация; предпочитайте более узкие области |
Запрос вне области действия ключа завершается 403 с кодом ошибки SCOPE_DENIED — выпустите ключ с нужной областью вместо расширения ключа существующего конвейера. Ключи, выпущенные до появления областей действия, ведут себя как full.
Срок жизни
Ключи самообслуживания всегда истекают — по умолчанию через 90 дней. При выпуске через API (а не портал) срок можно выбрать:
curl -X POST https://sandbox-api.k8s.tangovision.dev/api/v1/keys \
-H "Authorization: Bearer $PORTAL_JWT" \
-H "Content-Type: application/json" \
-d '{"label": "ci", "scope": "sandbox", "expiresInDays": 30}'expiresInDays принимает 1–365. Истёкший ключ получает 401 на следующем запросе; выпустите замену в портале (список ключей показывает дату истечения каждого, а статус меняется на истёк). Бессрочные ключи существуют только как операторские — напишите на developers@tango.vision, если сервису такой действительно нужен.
Отзыв
Отзыв — в портале или через API:
curl -X DELETE https://sandbox-api.k8s.tangovision.dev/api/v1/keys/<keyId> \
-H "Authorization: Bearer $PORTAL_JWT"Отзыв действует со следующего запроса ключа — каждый запрос заново проверяется по хранилищу ключей, без какого-либо кэша, так что наблюдаемая задержка распространения равна времени до вашего следующего запроса. (Формальное обязательство платформы — менее 5 минут глобально; на практике это секунды.) Если ключ утёк — немедленно отзовите его, выпустите замену и сообщите нам, чтобы вместе посмотреть журнал аудита.
Журнал аудита
Каждое событие ключа записывается: выпуск (кто выпустил, какая область, какой срок), использование (каждый аутентифицированный запрос: ключ, маршрут, IP-адрес, user agent), отказы (отозванные/истёкшие/неизвестные ключи, нарушения области действия) и отзыв. Записи хранятся 18 месяцев.
Из сессии портала можно запросить журнал своей организации:
curl "https://sandbox-api.k8s.tangovision.dev/api/v1/keys/audit?limit=50" \
-H "Authorization: Bearer $PORTAL_JWT"Фильтры: action (key.issued | key.used | key.revoked), keyId, limit (≤ 500). Журнал аудита читается только из активной сессии портала — API-ключ его прочитать не может, и это сделано намеренно: в записях есть IP-адреса, которым нечего делать за секретом CI.