Uprawnienia kluczy API decydują, co może zepsuć wyciekły klucz. W narzędziu do linków bezpieczny domyślny wzorzec to klucz przypięty do jednej przestrzeni roboczej, ograniczony do najniższej roli, która wykonuje zadanie, przechowywany jako hash z pepperem, mający własny limit żądań i ustawione wygaśnięcie. Klucz, który tylko tworzy linki, nie ma czego szukać przy webhookach, członkach ani rozliczeniach i nigdy nie powinien otwierać endpointu admina. To właśnie zasada najmniejszych uprawnień, a większość z niej sprowadza się do wyborów, które robisz w trzydzieści sekund potrzebnych na utworzenie klucza.
W ciągu ostatniego roku przeczytałem wiele konfiguracji automatyzacji i wzorzec się powtarza: ktoś w piątek po południu wkleja własny, wszechmocny klucz do n8n, działa, i nikt o tym nie myśli, dopóki ta osoba nie odejdzie albo eksport przepływu nie wyląduje na wspólnym dysku. Reszta wpisu opisuje, jak działają zakresy i role kluczy API w produkcie do krótkich linków, co faktycznie może każda rola i jak przekazać klucz narzędziu do automatyzacji bez oddawania przestrzeni roboczej.
Wpis uzupełnia naszą szerszą listę kontrolną bezpieczeństwa skracacza URL, która obejmuje skanowanie, podpisywanie webhooków i logi audytu na całej platformie. Ten przybliża sam klucz.
Co znaczą uprawnienia kluczy API w narzędziu do linków
API narzędzia do linków dotyka więcej niż linków. Ten sam token, który tworzy go.example.com/spring-sale, może, zależnie od uprawnień, czytać analitykę kliknięć, dodać domenę niestandardową, zaprosić członka albo zarejestrować webhook wysyłający każde zdarzenie na zewnętrzny serwer. To ostatnie mnie przeraża. Webhook to stały strumień danych, który ten, kto go utworzy, może skierować na dowolny serwer, a nikt w zespole nie musi tego zauważyć przez tygodnie.
Uprawnienia mają więc trzy osie. Gdzie klucz działa (które konto lub przestrzeń robocza)? Co może tam robić (czytać, pisać, administrować)? I jak długo oraz jak szybko? Definicja najmniejszych uprawnień w słowniku NIST (dostęp 2026-10-24) mówi, że każdy podmiot dostaje minimum uprawnień potrzebnych do pełnienia swojej funkcji, i wszystkie trzy osie wchodzą w jej skład. Klucz z prawami tylko do odczytu, który nigdy nie wygasa i nie ma limitu żądań, nadal ma zbyt duże uprawnienia w czasie.
Klucze API przypięte do przestrzeni roboczej: jeden klucz, jedna przestrzeń
W Elido każdy klucz jest tworzony w przestrzeni roboczej i w niej zostaje. Wywołaj nim endpointy innej przestrzeni roboczej, a dostaniesz 404, taką samą odpowiedź jak dla przestrzeni, która nie istnieje, więc klucz nie potrafi nawet potwierdzić, że inne przestrzenie robocze istnieją.
To ważniejsze, niż brzmi. Agencje i większe zespoły często należą do pięciu lub dziesięciu przestrzeni roboczych. Gdyby klucz osobisty dziedziczył wszystko, do czego sięga jego twórca, jeden wyciekły token z jednego projektu klienta otwierałby wszystkich klientów. Klucze przypięte do przestrzeni roboczej zawężają zasięg szkód do jednej przestrzeni.
Klucz jest też ograniczony do roli wybranej przy tworzeniu i nigdy nie przekracza bieżącej roli swojego twórcy. Efektywny dostęp to niższa z tych dwóch. Zdegraduj admina, który utworzył klucz, do editora. Klucz spada razem z nim. Niestandardowe uprawnienia przypisane temu członkowi również są odrzucane, gdy rola klucza jest niższa, bo opisują osobę, a nie klucz.
Klucze API oparte na rolach: co może każda rola
Klucze Elido używają tych samych czterech ról co ludzie: viewer, editor, admin i owner. Rolę wybierasz przy tworzeniu klucza; jeśli ją pominiesz, klucz domyślnie dostaje editor, co pokrywa typowe zadanie automatyzacji, czyli tworzenie linków i czytanie analityki, bez zasięgu admina.
Oto jak to wygląda w praktyce dla rzeczy, których zwykle dotykają integracje.
| Rola | Linki i kampanie | Analityka | Webhooki | Domeny, członkowie, klucze |
|---|---|---|---|---|
| viewer | Tylko odczyt | Odczyt, uruchamianie zadań eksportu CSV | Lista endpointów | Podgląd domen i członków |
| editor | Tworzenie, edycja, usuwanie, masowe tworzenie | Odczyt, uruchamianie zadań eksportu CSV | Lista endpointów | Podgląd domen i członków |
| admin | Wszystko, co editor | Plus konfiguracja eksportu danych do S3, zaplanowane raporty e-mail | Tworzenie, zmiana, odtwarzanie | Zarządzanie domenami, członkami, kluczami |
| owner | Wszystko | Wszystko | Wszystko | Wszystko |
Panel raportowy, który ściąga liczby kliknięć do narzędzia BI, potrzebuje viewer. Zadanie w Arkuszach Google, które tworzy linki kampanii, potrzebuje editor. Prawie nic w codziennej automatyzacji nie potrzebuje admina, a klucz owner uznałbym za zapach kodu: owner istnieje dla ludzi prowadzących przestrzeń roboczą i nie przychodzi mi do głowy żadne zadanie automatyzacji, które by go wymagało.
Warto znać dwa ograniczenia. Tylko admini i ownerzy mają uprawnienie api_keys.manage, więc klucz viewer lub editor nie może wyświetlać ani unieważniać kluczy. A utworzenie klucza lub zmiana jego limitu żądań wymaga zalogowanej osoby: klucz API dowolnej roli dostaje 403 ("this action requires an interactive session"). Wyciekły klucz admina nie może wyprodukować bezterminowego zastępnika. Nadal może jednak wyświetlać i unieważniać klucze. I żaden klucz żadnej roli nie dosięga API administratora platformy. Ta powierzchnia odrzuca uwierzytelnianie kluczem API wprost, z 403 i komunikatem "admin access requires an interactive session". Klucz służy integracji przestrzeni roboczej i tylko to otwiera.
Dlaczego zarządzanie webhookami wymaga klucza admina
To ta rzecz, która ludzi zaskakuje. Odczyt listy endpointów webhooków jest dozwolony dla każdego członka, także dla kluczy viewer. Ale utworzenie endpointu, zmiana jego celu czy odtworzenie dostawy wymagają uprawnienia workspace.edit, które mają tylko admin i owner.
Uzasadnienie to wspomniany wcześniej problem stałego strumienia. Editor może utworzyć tysiąc linków i to zauważysz. Editor, który mógłby dodać webhook typu catch-all skierowany na własny serwer, od tej pory po cichu dostawałby każde zdarzenie linku. Dlatego zmiany webhooków są u tych samych osób, które mogą zmieniać ustawienia przestrzeni roboczej.
W praktyce skonfiguruj webhooki raz, ręcznie, jako admin w panelu. Potem daj automatyzacji, która je konsumuje, klucz editor lub viewer do wywołań API. Jeśli podłączasz webhooki zdarzeń linków do Slacka lub CRM, strona odbierająca w ogóle nie potrzebuje klucza Elido; potrzebuje sekretu podpisu do weryfikacji ładunków.
Chcesz dowodu, zanim cokolwiek podłączysz? Utwórz darmową przestrzeń roboczą, wygeneruj klucz viewer i klucz editor i wywołaj tym samym zapisem każdy z nich. 403 na kluczu viewer powie Ci więcej niż każda tabela.
Jak przechowywane są klucze: pepper, hash i prefiks
Token wygląda jak elido_ plus 52 znaki base32, wygenerowane z 32 losowych bajtów. Widzisz go w całości dokładnie raz, w odpowiedzi na wywołanie tworzące. Potem znika z naszej strony na dobre.
Przechowujemy HMAC-SHA256 tokenu, z kluczem pepper po stronie serwera, który leży w konfiguracji aplikacji, a nie w bazie danych. Przy każdym żądaniu przychodzący token Bearer (schemat zdefiniowany w RFC 6750, dostęp 2026-10-24) jest haszowany w ten sam sposób i wyszukiwany po haszu. Skradziony zrzut bazy to więc lista haszy, których nikt nie sprawdzi bez peppera. Bez peppera nie ma startu: produkcyjna usługa odmawia uruchomienia, jeśli żaden nie jest ustawiony.
Na potrzeby własnych zapisów przechowujemy pierwsze osiem znaków po elido_ jako prefiks wyświetlany, a strona kluczy API pokazuje ten prefiks obok nazwy klucza, roli, daty utworzenia, wygaśnięcia, czasu ostatniego użycia i ostatniego użytego IP, a także łączną liczbę żądań i liczbę nieudanych. Gdy klucz pojawi się gdzieś w logu, prefiks mówi, który to. Nikt nie musi widzieć pełnego sekretu.
Limity żądań, wygasanie i rotacja kluczy API
Każdy klucz ma własny token bucket, oddzielny od limitu na przestrzeń roboczą, więc jeden rozszalały przepływ nie zje budżetu wszystkim innym. Zalogowany admin może nadpisać stawkę pojedynczego klucza od 1 do 10 000 żądań na sekundę i burst od 1 do 20 000 albo wyczyścić nadpisanie, by wrócić do domyślnego. Po przekroczeniu limitu klucz dostaje 429 z Retry-After: 1 i X-RateLimit-Scope: api_key, więc Twoja logika ponowień odróżni limit klucza od limitu przestrzeni roboczej. Przewodnik po limitach żądań i idempotentności opisuje właściwe wycofywanie się.
Wygaśnięcie jest opcjonalne i ustawiane przy tworzeniu jako znacznik czasu RFC 3339. Po jego upływie klucz po prostu przestaje pasować. Unieważnienie to jedno DELETE. Jest też idempotentne.
Nie ma jednego przycisku "rotuj" i nie brakuje mi go. Rotacja to trzy kroki:
- Utwórz nowy klucz z tą samą rolą i nowym wygaśnięciem.
- Podmień go w magazynie poświadczeń narzędzia i potwierdź, że wywołanie się udaje.
- Unieważnij stary klucz, a potem sprawdź na liście, czy jego czas ostatniego użycia przestał się przesuwać.
Każdy krok ląduje w logu audytu przestrzeni roboczej: api_key.created z nazwą i rolą, api_key.revoked oraz api_key.rate_limit_set dla nadpisań. Co pięć minut działa też skan w tle, który oznacza każdy klucz z ponad 1000 żądań, z których ponad 30% się nie powiodło. Flaga trafia do logu audytu i na klucz. Bez automatycznego unieważniania. Ubicie klucza to decyzja człowieka, bo seria 404 jest równie często zepsutym przepływem co atakującym.
Przekazywanie kluczy API o najmniejszych uprawnieniach do n8n, Make i Zapier
Platformy automatyzacji to miejsca, gdzie klucze idą, by o nich zapomnieć. Siedzą w magazynie poświadczeń, są kopiowane do wyeksportowanego JSON przepływu i przeżywają osobę, która je skonfigurowała. Pomagają dwa nawyki:
- Jeden klucz na narzędzie i rodzinę przepływów, nazwany od niego ("n8n: campaign sheets"). Unieważnienie psuje wtedy dokładnie jedną rzecz, a log audytu mówi, które narzędzie co zrobiło.
- Editor dla wszystkiego, co tworzy linki, viewer dla wszystkiego, co tylko czyta, i data wygaśnięcia na obu.
To cała lista; reszta to osąd. Secrets Management Cheat Sheet OWASP (dostęp 2026-10-24) to dobra lektura o trzymaniu tokenów poza logami i eksportami, czyli tam, gdzie klucze automatyzacji zwykle wyciekają.
Konfigurację w konkretnych narzędziach opisuje przewodnik po skracaczu URL w n8n, który umieszcza klucz w poświadczeniu Header Auth, a porównanie Make, IFTTT, n8n i Zapier pokazuje, gdzie każda platforma go trzyma. Zapier łączy się tym samym tokenem, zgodnie z omówieniem automatyzacji w Zapier. Dla CI lub czegokolwiek, co powinno przetrwać odejście osoby, lepszy jest użytkownik maszynowy: konto usługi z własnym tokenem, oddzielone od klucza dowolnego człowieka. Podobnie jak klucze, użytkownicy maszynowi są tworzeni przez zalogowanego admina, nigdy przez token.
A powód, dla którego klucz nigdy nie może otwierać endpointów admina, to właśnie to przekazanie. Gdy token siedzi w narzędziu zewnętrznym, każdy z dostępem do edycji przepływów tego narzędzia może go użyć. Ufasz wszystkim po ich stronie, nie tylko po swojej.
Tokeny z zakresami są planowane, nie działają
Role są celowo grube i czasem zbyt grube. Klucz editor, który tylko tworzy linki, może je też usuwać, bo usuwanie należy do roli editor. Remedium to tokeny z zakresami, takimi jak links:write lub analytics:read, przypisane bezpośrednio do klucza, nałożone na role.
To jest w naszej mapie drogowej i nie zostało wydane. Dziś uprawnienia klucza to jego przestrzeń robocza plus rola i nic drobniejszego. Jeśli potrzebujesz ciaśniejszej kontroli już teraz, masz dwie dźwignie: niższą rolę i krótkie wygaśnięcie, a także osobne klucze na zadanie, by zasięg szkód każdego był mały. Szybki start API i dokumentacja API i SDK pokazują obecny model kluczy w działającym kodzie, a zespoły chcące też kontroli na poziomie tożsamości mogą przeczytać o SCIM i SSO w narzędziach marketingowych.
Przeczytaj materiał główny: lista kontrolna bezpieczeństwa skracacza URL opisuje zabezpieczenia wokół klucza, od skanowania URL po listy dozwolonych IP.
Powiązane na blogu
Najczęściej zadawane pytania
Czym są uprawnienia kluczy API?
To zestaw akcji, które klucz może wykonywać w API: jakie zasoby może czytać, jakie zmieniać i na którym koncie. W Elido uprawnienia klucza wynikają z przestrzeni roboczej, w której go wydano, oraz z roli wybranej przy tworzeniu, więc ten sam klucz nie może działać w innej przestrzeni roboczej ani powyżej tej roli.
Czym jest zasada najmniejszych uprawnień dla kluczy API?
Oznacza, że każdy klucz dostaje najmniejszy zestaw uprawnień potrzebny do swojego zadania i nic ponad to. Panel, który tylko czyta liczby kliknięć, dostaje klucz viewer, przepływ tworzący linki dostaje klucz editor, a klucze admin zostawia się na rzadkie zadania zarządzające webhookami, domenami lub członkami. Wyciekły klucz może wtedy zrobić tylko to, co robiło jego jedno zadanie.
Czym różnią się zakresy (scopes) kluczy API od ról?
Zakres to wąskie uprawnienie, takie jak links:write, przypisane bezpośrednio do tokena, a rola to nazwany pakiet uprawnień, taki jak editor. Role łatwiej ogarnąć; zakresy są drobniejsze. Klucze Elido używają dziś ról przestrzeni roboczej, a tokeny z zakresami są planowane na ich bazie, ale jeszcze nie działają.
Jak często rotować klucze API?
Typowe zalecenie to co 30-90 dni, a ponadto natychmiast, gdy odchodzi ktoś, kto widział klucz, klucz pojawi się w logu albo jego ruch wygląda nieprawidłowo. Ustawienie daty wygaśnięcia przy tworzeniu zamienia ten harmonogram w twardy stop zamiast przypomnienia w kalendarzu, które ludzie ignorują.
Czy klucz API może uzyskać dostęp do endpointów admina?
W Elido nie. API administratora platformy przyjmuje tylko interaktywną, zalogowaną sesję i na klucz API odpowiada 403, niezależnie od roli osoby, która go utworzyła. Ustawienia przestrzeni roboczej wymagające praw admina nadal są osiągalne, ale tylko dla klucza utworzonego z rolą admin lub owner.
Jak dostawca powinien przechowywać klucze API po swojej stronie?
Nigdy jawnym tekstem. Dostawca powinien zapisywać hash tokena z kluczem i potem pokazywać Ci tylko krótki prefiks, żeby sama kopia bazy nie pozwalała wywoływać API. Elido hashuje każdy token przez HMAC-SHA256 z pepperem po stronie serwera i pokazuje pełny token dokładnie raz.
Wypróbuj Elido
Wklej URL, otrzymaj krótki link
Bez rejestracji. Link działa 30 dni. Zarejestruj się, aby zachować go na zawsze.
Bez rejestracji. Załóż darmowe konto i korzystaj z 50 linków miesięcznie.