Що ви зробите
- Оновіть ключ без простоїв — спочатку видайте замінний ключ, а старий відкличте лише після підтвердження роботи нового.
- Негайно відкличте скомпрометований ключ — поширення на всі регіони займає не більше 60 секунд.
- Зберігайте ключі у змінних оточення або secret manager, але не в коді, та оновлюйте їх, коли учасник із доступом залишає команду.
API ключі — це довготривалі bearer tokens, тому планове оновлення (rotation) та їх негайне відкликання у разі витоку варто робити правильно. У цій статті описано обидва випадки.
Оновлення ключа без простоїв#
Оновлення (rotation) означає випуск нового ключа перед тим, як ви вилучите старий, щоб не було перерви, коли ваша інтеграція залишається неавтентифікованою.
- Перейдіть до розділу Settings → API keys і натисніть Generate key.
- Дайте новому ключу назву, яка чітко пояснює його призначення (наприклад,
production-v2). - Виберіть ту саму роль, що й у ключа, який ви замінюєте.
- Скопіюйте токен — він відображається лише один раз.
- Оновіть свою змінну оточення або secret manager новим токеном і виконайте деплой.
- Коли новий ключ запрацює і ви підтвердите його працездатність (перевірте стовпець Last used — значення має змінитися протягом кількох хвилин), поверніться до Settings → API keys і натисніть Revoke біля старого ключа.
Залишайте старий ключ активним, поки не переконаєтеся, що новий працює. Якщо ви відкличете його занадто рано, а деплой ще не завершився, трафік отримуватиме помилки 401.
Негайне відкликання скомпрометованого ключа#
Якщо ключ було розкрито — опубліковано у публічному репозиторії, зафіксовано в логах або включено у клієнтський бандл — спочатку відкличте його, а вже потім проводьте розслідування.
- Settings → API keys, знайдіть ключ за його назвою або префіксом (префікс відображається в таблиці, навіть якщо повний токен приховано).
- Натисніть Revoke. Відкликання поширюється на всі регіони протягом 60 секунд.
- Випустіть новий ключ на заміну та оновіть свої секрети.
- Перевірте мітку часу 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 і не мають кнопок дій. Переконайтеся, що ви переглядаєте правильний workspace — ключі обмежені робочим простором.
60-секундне вікно поширення. Якщо ви відкликнули ключ, а запити все ще успішно проходять протягом короткого часу — це очікувано. Наші edge nodes синхронізують відкликання через Redis pub/sub; максимальна затримка становить приблизно 60 секунд.
Ключ зник зі списку. Ми зберігаємо відкликані ключі в таблиці необмежений час для цілей аудиту. Якщо ви не можете його знайти, перевірте, чи не застосовано фільтри до списку — за замовчуванням фільтра лише для активних ключів немає, але текстовий пошук за полем назви приховає рядки, що не відповідають запиту.