Смена или отзыв 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 секунд.

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