Co zrobisz
- Przeprowadzisz rotację klucza bez przestojów, wystawiając zamiennik przed unieważnieniem starego — dopiero po potwierdzeniu, że nowy klucz działa.
- Natychmiast unieważnisz wyciekły klucz — propagacja do wszystkich regionów trwa maksymalnie 60 sekund.
- Będziesz przechowywać klucze w zmiennych środowiskowych lub menedżerze sekretów, nigdy w kodzie, i wykonywać rotację przy zmianie składu zespołu.
Klucze API to długożyjące tokeny typu bearer, więc ich okresowa rotacja — oraz natychmiastowe unieważnienie w przypadku wycieku — jest praktyką wartą rzetelnego wdrożenia. Ten artykuł omawia oba przypadki.
Rotacja klucza bez przestojów#
Rotacja polega na wystawieniu nowego klucza przed wycofaniem starego, co eliminuje lukę, w której Twoja integracja pozostałaby bez uwierzytelnienia.
- Przejdź do Settings → API keys i kliknij Generate key.
- Nadaj nowemu kluczowi nazwę jasno określającą jego przeznaczenie (np.
production-v2). - Wybierz tę samą rolę, którą posiadał zastępowany klucz.
- Skopiuj token — zostanie wyświetlony tylko raz.
- Zaktualizuj zmienną środowiskową lub menedżera sekretów nowym tokenem i wykonaj wdrożenie (deploy).
- Gdy nowy klucz będzie aktywny i potwierdzisz jego działanie (sprawdź kolumnę Last used — status powinien zmienić się w ciągu kilku minut), wróć do Settings → API keys i kliknij Revoke przy starym kluczu.
Utrzymuj stary klucz jako aktywny, dopóki nie upewnisz się, że nowy działa poprawnie. Jeśli unieważnisz go zbyt wcześnie, a wdrożenie nie zostanie zakończone, ruch zacznie zwracać błędy 401.
Natychmiastowe unieważnienie wyciekłego klucza#
Jeśli klucz został ujawniony — przesłany do publicznego repozytorium, wyciekł w logach lub znalazł się w pakiecie klienckim (client-side bundle) — najpierw go unieważnij, a dopiero potem badaj przyczynę.
- W Settings → API keys znajdź klucz po jego nazwie lub prefiksie (prefiks jest widoczny w tabeli, nawet jeśli pełny token pozostaje ukryty).
- Kliknij Revoke. Unieważnienie rozpropaguje się do wszystkich regionów w ciągu 60 sekund.
- Wystaw klucz zamienny i zaktualizuj swoje sekrety.
- Sprawdź znacznik czasu Last used na unieważnionym kluczu, aby oszacować, jak długo był narażony na nieautoryzowane użycie i czy konieczny jest audyt pod kątem podejrzanej aktywności.
Unieważnione klucze są przechowywane w tabeli z oznaczeniem revoked, aby zachować historię. Nie można ich ponownie aktywować.
Bezpieczna aktualizacja sekretów#
Standardowym wzorcem jest przechowywanie kluczy w zmiennych środowiskowych, a nie bezpośrednio w kodzie:
# .env.local (nigdy nie zatwierdzaj w repozytorium)
ELIDO_API_KEY=elido_live_xxx...
import { ElidoClient } from "@elido/sdk";
const client = new ElidoClient({ apiKey: process.env.ELIDO_API_KEY! });
W przypadku potoków CI korzystaj z magazynu sekretów Twojej platformy (np. GitHub Actions secrets, GitLab CI variables) i wykonuj rotację za każdym razem, gdy członek zespołu z dostępem do nich opuszcza organizację.
Co dzieje się z aktywnymi integracjami#
Gdy unieważniasz klucz, wszelkie trwające żądania, które już wysłały token, zostaną ukończone — walidacja odbywa się na początku żądania, a nie w trakcie odpowiedzi. Żądania rozpoczęte po unieważnieniu zwrócą błąd 401 Unauthorized. Biblioteki SDK nie ponawiają prób po otrzymaniu 401 (co zapobiega pętli), więc Twoja integracja natychmiast zacznie zgłaszać błędy.
Zaplanuj krótkie okno czasowe, w którym oba klucze będą się pokrywać: zachowaj stary klucz aktywny, dopóki nie potwierdzisz, że nowy działa na produkcji.
Rozwiązywanie problemów#
401 przy nowo utworzonym kluczu. Token wyświetlany w momencie tworzenia to pełny klucz zawierający tajny sufiks. Jeśli skopiowano tylko prefiks z tabeli (np. elido_abc123), nie będzie on działać — prefiks służy wyłącznie do celów identyfikacji wizualnej. Wygeneruj nowy klucz i skopiuj pełny token.
Brak przycisku Revoke. Klucz prawdopodobnie został już unieważniony. Unieważnione klucze posiadają odznakę revoked i nie mają dostępnych przycisków akcji. Upewnij się, że przeglądasz właściwy obszar roboczy (workspace) — klucze mają przypisany zakres do konkretnego workspace.
60-sekundowe okno propagacji. Jeśli po unieważnieniu klucza żądania przez krótką chwilę nadal kończą się sukcesem, jest to zjawisko oczekiwane. Nasze węzły brzegowe (edge nodes) synchronizują unieważnienia przez Redis pub/sub; w najgorszym wypadku opóźnienie wynosi około 60 sekund.
Klucz zniknął z listy. Przechowujemy unieważnione klucze w tabeli bezterminowo do celów audytowych. Jeśli nie możesz go znaleźć, sprawdź, czy lista nie jest przefiltrowana — domyślnie nie stosujemy filtra tylko dla aktywnych kluczy, ale wyszukiwanie tekstowe po nazwie ukryje wiersze, które do niego nie pasują.