Смена или отзыв API-ключа

API-ключи — это долгоживущие bearer tokens, поэтому их плановая ротация и немедленный отзыв в случае утечки — это важные меры безопасности. В этой статье рассматриваются оба случая.

Смена ключа без простоя#

Ротация означает выпуск нового ключа перед тем, как вы отзовете старый, чтобы не было перерыва, когда ваша интеграция не аутентифицирована.

1. Перейдите в Settings → API keys и нажмите Generate key.
2. Дайте новому ключу имя, которое четко отражает его назначение (например, production-v2).
3. Выберите ту же роль, что и у ключа, который вы заменяете.
4. Скопируйте токен — он показывается только один раз.
5. Обновите свою переменную окружения или secret manager новым токеном и выполните деплой.
6. Как только новый ключ заработает и это будет подтверждено (проверьте колонку Last used — она должна обновиться в течение нескольких минут), вернитесь в Settings → API keys и нажмите Revoke у старого ключа.

Держите старый ключ активным, пока не убедитесь, что новый работает. Если вы отзовете его слишком рано до завершения деплоя, трафик будет получать ошибки 401.

Немедленный отзыв скомпрометированного ключа#

Если ключ был скомпрометирован — попал в публичный репозиторий, засветился в логах или в клиентском бандле — сначала отзовите его, а расследование проводите потом.

1. Settings → API keys, найдите ключ по его имени или префиксу (префикс виден в таблице, даже если полный токен — нет).
2. Нажмите Revoke. Отзыв распространится на все регионы в течение 60 секунд.
3. Выпустите замену ключа и обновите свои секреты.
4. Проверьте временную метку Last used на отозванном ключе, чтобы оценить, как долго он был открыт и нужно ли проводить аудит на предмет подозрительной активности.

Отозванные ключи сохраняются в таблице с меткой revoked для истории. Их нельзя активировать повторно.

Безопасное обновление секретов#

Стандартный паттерн — хранить ключи в переменных окружения, а не в коде:

# .env.local (never committed)
ELIDO_API_KEY=elido_live_xxx...

import { ElidoClient } from "@elido/sdk";

const client = new ElidoClient({ apiKey: process.env.ELIDO_API_KEY! });

Для CI-конвейеров используйте хранилище секретов вашей платформы (GitHub Actions secrets, GitLab CI variables и т. д.) и проводите ротацию каждый раз, когда член команды с доступом покидает проект.

Что происходит с активными интеграциями#

Когда вы отзываете ключ, любые текущие запросы, которые уже отправили токен, будут завершены — мы проводим валидацию в начале запроса, а не в середине ответа. Запросы, которые начнутся после отзыва, вернут 401 Unauthorized. SDK не выполняют повторных попыток при 401 (это привело бы к циклу), поэтому ваша интеграция сразу начнет выдавать ошибки.

Запланируйте небольшое окно перекрытия: держите старый ключ активным, пока не подтвердите, что новый активен в продакшене.

Устранение неполадок#

401 на ключе, который вы только что создали. Токен, отображаемый при создании — это полный ключ, включая секретный суффикс. Если вы скопировали из таблицы только префикс (например, elido_abc123), это не сработает — префикс предназначен только для отображения. Выпустите новый ключ и скопируйте полный токен.

Кнопка Revoke отсутствует. Вероятно, ключ уже отозван. Отозванные ключи имеют значок revoked и не имеют кнопок действий. Убедитесь, что вы смотрите правильный воркспейс — ключи привязаны к рабочим пространствам.

60-секундное окно распространения. Если вы отзывали ключ, а запросы все еще проходят в течение какого-то времени, это ожидаемо. Наши edge nodes синхронизируют отзыв через Redis pub/sub; максимальная задержка составляет ~60 секунд.

Ключ исчез из списка. Мы храним отозванные ключи в таблице неограниченное время для целей аудита. Если вы не можете его найти, проверьте, не применены ли фильтры к списку — по умолчанию фильтра "только активные" нет, но текстовый поиск по полю имени скроет несовпадающие строки.