Klucz API: co to jest i jak go bezpiecznie przechowywać
Klucz API to hasło programu do innego programu. Czym różni się od tokena i JWT, jak go wysłać, gdzie trzymać i jak wymienić po wycieku.
Klucz API to długi, losowy ciąg znaków, którym jeden program przedstawia się drugiemu. Wklejasz go, gdy sklep internetowy, CRM albo system do faktur prosi o „klucz API” innej usługi, a twórca integracji wpisuje go do kodu, który rozmawia z cudzym serwerem. Kto ma klucz, działa w imieniu jego właściciela — dlatego trzeba go chronić jak hasło, choć hasłem do logowania nie jest. Poniżej: czym klucz różni się od tokena OAuth i JWT, dlaczego nie wysyła się go w adresie URL (sprawdziliśmy, co zostaje w logu serwera), jak klucz wygląda od środka u dostawcy, gdzie go trzymać i jak wymienić bez przestoju. Przykładem jest nasze API — z zapytaniami do lokalnej instancji tego samego kodu, który działa na produkcji.
Klucz API — co to jest i do czego służy
Klucz API identyfikuje aplikację, a nie człowieka. Gdy integracja sklepu tworzy krótkie linki w skracaczu, serwer skracacza nie wie, kto siedzi przy klawiaturze — widzi klucz i na jego podstawie ustala, do którego konta należy żądanie, co wolno z nim zrobić i ile takich żądań zostało w limicie. Z tego wynika najważniejsza zasada: każdy, kto zdobędzie klucz, może zrobić to samo co Twoja integracja.
OWASP, organizacja zajmująca się bezpieczeństwem aplikacji, ujmuje różnicę między kluczem a logowaniem wprost: „OAuth is not authentication, and neither are API keys”. Klucze API „should not be used for user authentication. They should only be used for API clients authentication” (OWASP API Security Top 10 2023, API2). Klucz mówi więc „to jest integracja X konta Y”, a nie „to jest Jan Kowalski”.
Każdy dostawca ma własny format i własny panel do tworzenia kluczy — klucz do map Google wygląda i działa inaczej niż klucz do skracacza linków. Zasady bezpieczeństwa są jednak wspólne. Google Cloud ostrzega, że publicznie ujawniony klucz może skończyć się „unexpected charges on your account or unauthorized access to your data” (Google Cloud, API keys best practices). Przy płatnym API wyciek klucza to więc także rachunek.
Klucz jest potrzebny tam, gdzie program rozmawia z programem przez REST API. Jak takie API działa — metody, adresy, kody odpowiedzi — opisuje tekst o REST API. Tutaj zajmujemy się tylko kluczem.
Klucz API a token, OAuth i JWT
Klucz API, token dostępu OAuth, JWT i hasło bywają wrzucane do jednego worka, bo wszystkie są „sekretnym ciągiem znaków”. Różnią się jednak tym, kogo wskazują, kto je wydaje i jak długo żyją.
Token dostępu OAuth to według specyfikacji „a string representing an authorization issued to the client” — zgoda wydana aplikacji, z określonym zakresem i czasem dostępu, którą przyznaje właściciel zasobu (RFC 6749, §1.4). Typowy przykład: logujesz się do aplikacji przez konto Google i zgadzasz się, żeby odczytała Twój kalendarz. Aplikacja dostaje token, który działa w Twoim imieniu i tylko w zakresie, na który się zgodziłeś.
JWT (JSON Web Token) to format, a nie osobny rodzaj uprawnienia: „a compact, URL-safe means of representing claims to be transferred between two parties” (RFC 7519). W środku są dane zapisane jako JSON, podpisane albo zaszyfrowane, w tym opcjonalnie pole exp z datą, po której token „MUST NOT be accepted”. Token OAuth bywa JWT-em, ale nie musi.
Klucz API jest prostszy: to losowy ciąg bez żadnego znaczenia, wydany w panelu dostawcy dla aplikacji, ważny do wyłączenia albo do daty ważności, jeśli ją ustawiono.
Klucz API, token OAuth, JWT i hasło — czym się różnią
kogo wskazują, kto je wydaje, jak długo żyją i jak się je wysyła
Źródło: RFC 6750 §1.2, RFC 7519, OWASP API Security Top 10 2023 (API2); odczyt 21.10.2026
Opis figury
Tabela czterech kolumn. Klucz API: wskazuje aplikację lub integrację, wydaje panel dostawcy API, żyje do wyłączenia albo daty ważności, to losowy ciąg bez znaczenia, wysyła się go w nagłówku, np. Authorization: Bearer. Token dostępu OAuth: aplikacja działająca w imieniu użytkownika, wydaje serwer autoryzacji po zgodzie użytkownika, zwykle krótko, potem odświeżenie, przepustka z zakresem, Authorization: Bearer. JWT: wskazuje to, co zapisano w środku, wydaje ten, kto podpisuje, do daty w polu exp, jeśli jest, format dane plus podpis, zwykle jako token Bearer. Hasło: człowieka, ustala użytkownik, do zmiany, sekret do logowania, formularz logowania, nie API.
Wspólne dla trzech pierwszych jest słowo „bearer”, które zobaczysz w nagłówku Authorization: Bearer. Specyfikacja definiuje bearer token jako taki, którego „any party in possession of the token (a "bearer") can use” — używać może każdy, kto go ma, bez dowodu, że jest prawowitym właścicielem (RFC 6750, §1.2). Dlatego tokenom OAuth daje się krótkie życie: RFC zaleca, by serwery wydawały je na „one hour or less”, co ogranicza skutki wycieku (RFC 6750, §5.3). Klucz API zwykle żyje znacznie dłużej i właśnie dlatego wymaga więcej dyscypliny przy przechowywaniu.
Jak wysłać klucz API: nagłówek, nie adres URL
Klucz API wysyłaj w nagłówku HTTP — najczęściej Authorization: Bearer <klucz>, u niektórych dostawców we własnym nagłówku, jak x-goog-api-key w Google. Nigdy w adresie URL, choć wiele API to umożliwia — nasze też, ale tę możliwość wycofujemy.
Specyfikacja jest tu jednoznaczna. Przekazywanie tokenu w parametrze adresu „SHOULD NOT be used”, chyba że nie da się go wysłać w nagłówku ani w treści żądania, bo adres z tokenem bardzo łatwo trafia do logów (RFC 6750, §2.3). Dalej RFC tłumaczy, że przeglądarki, serwery WWW i inne oprogramowanie „may not adequately secure URLs in the browser history, web server logs, and other data structures” (RFC 6750, §5.3). Google mówi to samo o swoich kluczach: klucz w parametrze naraża go na kradzież „through URL scans” (Google Cloud), a OWASP zalicza wysyłanie tokenów w adresie do podatności API.
Sprawdziliśmy, jak to wygląda w praktyce. Przed lokalną instancją naszego API postawiliśmy nginx w roli serwera pośredniczącego (reverse proxy), z domyślnym formatem logu, i wysłaliśmy to samo zapytanie dwa razy: z kluczem testowym w adresie i w nagłówku.
Klucz w adresie zostaje w logu, klucz w nagłówku — nie
log dostępu nginx przed lokalną instancją API; klucz testowy skrócony na figurze
Pomiar: nginx 1.29.3 przed lokalną instancją API v1, 21.10.2026
Opis figury
Dwa panele. Klucz w adresie, ?api_key=: w logu dostępu nginx 1.29.3 z ustawieniami domyślnymi zapisała się linia GET /api/v1/links?limit=1&api_key= z pełnym kluczem, status 200; nasze API odpowiedziało 200 z nagłówkami Deprecation: @1792540800 i Warning: 299 o wycofaniu parametru api_key. Klucz w nagłówku Authorization: Bearer: w logu linia GET /api/v1/links?limit=1 bez klucza, status 200.
W logu dostępu linia z zapytaniem zawiera cały adres, łącznie z parametrami — więc i pełny klucz. Nagłówka Authorization domyślny format logu nie zapisuje. Tymczasem sekrety według OWASP powinny „Never be logged”, a log czyta każdy, kto ma dostęp do serwera. Ten sam adres zostaje też w historii przeglądarki, jeśli ktoś otworzy go ręcznie.
Nasze API przyjmowało dotąd klucz także w parametrze ?api_key=. Od 21 października 2026 roku ten sposób jest wycofywany: żądania z kluczem w adresie nadal działają, żeby istniejące integracje się nie zepsuły, ale odpowiedź dostaje nagłówek Deprecation z datą wycofania i Warning z informacją, żeby przenieść klucz do nagłówka Authorization. Jeśli Twoja integracja go używa — zmień to teraz. Budowę adresu opisuje tekst o adresie URL, a to, co robi część po znaku zapytania — tekst o query stringu.
Jak dostawca przechowuje klucz API
Dobrze zbudowany klucz API ma dwie części: rozpoznawalny prefiks i losową resztę, którą dostawca przechowuje tylko w postaci skrótu. Pokazujemy to na naszych kluczach, bo kod znamy od środka.
Anatomia klucza API — co widzisz Ty, a co zapisuje serwer
przykładowy klucz w formacie DVN Links; pomiar na 10 000 wygenerowanych kluczy
Pomiar: funkcje z src/collections/ApiKeys.ts, 21.10.2026, procesor AMD Ryzen 9 9950X3D
Opis figury
Klucz podzielony na trzy części: prefiks dostawcy dvn*live* (9 znaków, stały), 7 znaków losowych zapisanych jawnie w bazie i pokazywanych w panelu oraz 25 znaków losowych nigdzie niezapisanych wprost. Ty widzisz cały klucz, 41 znaków, raz, przy tworzeniu. Baza danych zapisuje keyPrefix, czyli pierwsze 16 znaków do szybkiego wyszukania, i hash bcrypt o długości 60 znaków zaczynający się od $2b$10$. Panel pokazuje prefiks z wielokropkiem, ostatnie użycie, status i datę ważności. 10 000 wygenerowanych kluczy miało zawsze 41 znaków z alfabetu A–Z, a–z, 0–9, minus i podkreślnik. Część losowa: 32 znaki razy 6 bitów, czyli 192 bity. Bcrypt z kosztem 10: zapis 42 ms, sprawdzenie 42 ms, mediana z 20 prób.
Nasz klucz zaczyna się od dvn_live_, po którym idą 32 losowe znaki z alfabetu base64url. Wygenerowaliśmy 10 000 kluczy tą samą funkcją, której używa serwer: wszystkie miały 41 znaków. Każdy znak części losowej niesie 6 bitów, więc losowość to 192 bity — to nasze wyliczenie, nie wynik pomiaru.
Prefiks nie jest ozdobą. GitHub, opisując, jak dostawcy powinni projektować sekrety, żeby dało się je wykrywać w kodzie, wymienia „a uniquely defined prefix” i „high entropy random strings” (GitHub, program partnerski secret scanning). Prefiks pozwala też Tobie znaleźć zgubiony klucz w repozytorium jednym wyszukaniem frazy dvn_live_.
Najważniejsze dzieje się w bazie. Pełnego klucza nie zapisujemy. Zapisujemy jego pierwsze 16 znaków (prefiks plus 7 znaków losowych) i hash bcrypt całości. Hash działa w jedną stronę: z klucza łatwo go policzyć, z hasha klucza odtworzyć się nie da. To różnica między haszowaniem a szyfrowaniem — zaszyfrowany klucz dałoby się odszyfrować, zahaszowanego nie. Dlatego klucz widzisz tylko raz, zaraz po utworzeniu. Ani panel, ani obsługa klienta nie pokażą go ponownie; jeśli go zgubisz, tworzysz nowy.
Po co jawne 16 znaków? Bcrypt jest celowo wolny: w naszym pomiarze jedno sprawdzenie klucza trwało 42 ms. Gdyby serwer miał porównać przychodzący klucz z hashem każdego klucza w bazie, przy tysiącu kluczy zajęłoby to około 42 sekund — to nasze wyliczenie z pomiaru. Prefiks zawęża wyszukiwanie do jednego, najwyżej kilku kandydatów, a dopiero ich sprawdza się bcryptem. Zanim serwer w ogóle zajrzy do bazy, odrzuca klucz o złym formacie — bez prefiksu dvn_live_ albo o innej długości niż 41 znaków dostaje od razu 401 INVALID_API_KEY_FORMAT.
Z tego wynika prosty test, którym ocenisz dowolnego dostawcę API, zanim mu zaufasz:
- Czy pokazuje klucz tylko raz? Jeśli panel potrafi wyświetlić pełny klucz po tygodniu, dostawca przechowuje go w postaci, którą da się odczytać — a więc da się go też wykraść z jego bazy.
- Czy pozwala mieć kilka aktywnych kluczy? Bez tego każda wymiana klucza oznacza przerwę w działaniu integracji.
- Czy klucz da się wyłączyć jednym kliknięciem? Po wycieku liczą się minuty, nie zgłoszenie do obsługi klienta.
- Czy klucz może wygasnąć i mieć węższe uprawnienia? To ogranicza szkody, gdy wszystkie inne zabezpieczenia zawiodą.
Jak utworzyć klucz w naszym panelu, krok po kroku, opisuje dokumentacja kluczy API.
Gdzie trzymać klucz API (i gdzie nigdy)
Miejsce przechowywania klucza decyduje o tym, kto może go przeczytać. Od najgorszego do najlepszego:
|
Gdzie |
Kto może przeczytać klucz |
Werdykt |
|---|---|---|
|
kod strony WWW albo aplikacji mobilnej |
każdy użytkownik — wystarczą narzędzia deweloperskie przeglądarki |
nigdy |
|
plik w repozytorium (także prywatnym) |
każdy z dostępem do repozytorium, na zawsze — zostaje w historii Git |
nigdy |
|
plik |
każdy z dostępem do serwera albo komputera |
dopuszczalne lokalnie, przy pracy |
|
zmienna środowiskowa na serwerze |
wszystkie procesy na maszynie; może trafić do logów i zrzutów pamięci |
gdy nie ma lepszej opcji |
|
menedżer sekretów (np. sejf w chmurze) |
tylko usługa i osoby, którym nadasz dostęp |
docelowo |
Dwa najgorsze miejsca wykluczają się same. Google Cloud: nie umieszczaj kluczy w kodzie klienta ani w repozytorium, bo „API keys hardcoded in the source code or stored in a repository are open to interception or theft”; aplikacja kliencka powinna wysyłać żądanie do własnego serwera, a dopiero on dołącza klucz (Google Cloud). Klucz usunięty z repozytorium w kolejnym commicie nadal jest w historii — GitHub w swoim skanowaniu przegląda „your entire Git history on all branches” (GitHub, secret scanning), tak samo może zrobić każdy, kto sklonuje repozytorium.
Ciekawszy jest środek tabeli. W poradnikach zmienna środowiskowa uchodzi za złoty standard. OWASP jest ostrożniejszy: zmienne środowiskowe „are generally accessible to all processes and may be included in logs or system dumps”, więc ich używanie „is therefore not recommended unless the other methods are not possible” (OWASP, Secrets Management Cheat Sheet). Ta rada pada w części o kontenerach i nie znaczy, że zmienna jest zła — jest lepsza niż kod, gorsza niż menedżer sekretów. Jeśli Twoja platforma ma menedżer sekretów, użyj go.
Dwie siatki bezpieczeństwa warto mieć niezależnie od tego, gdzie trzymasz klucz. OWASP radzi włączyć wykrywanie sekretów u programisty — w edytorze albo „via pre-commit hook”, zanim cokolwiek trafi do repozytorium. GitHub ma do tego blokadę wysyłki (push protection), która zatrzymuje push zawierający sekret, „before they reach your repository” (GitHub, push protection). W repozytoriach publicznych skanowanie sekretów GitHub uruchamia automatycznie i za darmo.
Klucz API w integracji: jeden klucz na jedno narzędzie
Gdy kilka narzędzi korzysta z tego samego API, każde powinno dostać własny klucz. Jeden wspólny klucz wklejony do sklepu, do arkusza z automatyzacją i do skryptu kolegi oznacza, że po wycieku nie wiesz, skąd wyciekł, a wyłączenie go zatrzymuje wszystkie trzy integracje naraz.
Przed wklejeniem klucza do cudzego narzędzia zadaj sobie trzy pytania:
- Czego to narzędzie naprawdę potrzebuje? Jeśli ma tylko czytać statystyki, nie powinno móc kasować danych. Tam, gdzie dostawca pozwala wybrać zakres, wybierz najwęższy.
- Jak nazwę klucz? Nazwa w panelu powinna mówić, gdzie klucz trafił — „Sklep, eksport linków” zamiast „klucz 2”. Po roku nikt nie pamięta, który klucz jest gdzie.
- Kiedy ma wygasnąć? Klucz do testu albo do jednorazowej kampanii nie musi żyć dłużej niż kilka tygodni.
W naszym panelu nazwę i ważność ustawiasz przy tworzeniu klucza, a lista kluczy pokazuje przy każdym prefiks, datę ostatniego użycia i status. Zasada „jeden klucz na jedno narzędzie” ma u nas jeden koszt: wszystkie klucze konta dzielą ten sam limit zapytań, o czym niżej.
Zakresy, limity i wygasanie klucza API
Klucz może mieć ograniczenia, które zmniejszają szkody, gdy wycieknie: zakres uprawnień, limit zapytań i datę ważności. Google radzi dodawać do kluczy ograniczenia, bo „you can limit the ways an API key can be used, reducing the impact of a compromised API key” (Google Cloud).
Zakresy. Klucz, który tylko czyta statystyki, nie powinien móc kasować danych. Nasze API sprawdza pięć zakresów: links:read, links:write, stats:read, cards:read i cards:write. Klucz bez potrzebnego zakresu dostaje 403 INSUFFICIENT_PERMISSIONS — w pomiarze klucz z samym links:read nie utworzył linku. Uczciwie: klucz utworzony w naszym panelu dostaje dziś wszystkie pięć zakresów, a węższego w panelu nie wybierzesz.
Limity. Dostawca liczy zapytania na klucz albo na konto i po przekroczeniu odpowiada kodem 429 Too Many Requests, opcjonalnie z nagłówkiem Retry-After, który mówi, ile czekać (RFC 6585, §4). U nas limity zależą od planu i obowiązują całe konto — wszystkie klucze dzielą jedną pulę:
Limity naszego API według planu — na konto, nie na klucz
zapytania na godzinę (skala logarytmiczna) i na minutę; pomiar z dwoma kluczami
Źródło: src/seed/plans.ts (limity planów); pomiar na lokalnej instancji, 21.10.2026
Opis figury
Wykres słupkowy. Darmowy: bez API. Starter: 100 zapytań na godzinę i 50 na minutę. Pro: 10 000 na godzinę i 200 na minutę. Business: 50 000 na godzinę i 500 na minutę. Enterprise: bez limitu. Pomiar: konto Starter, dwa klucze na zmianę — 429 przy 51. zapytaniu, po 25 udanych z każdego klucza, X-RateLimit-Limit 50. Po przekroczeniu: 429 Too Many Requests i Retry-After w sekundach.
Sprawdziliśmy to dwoma kluczami jednego konta Starter, używanymi na zmianę: odmowa przyszła przy 51. zapytaniu, po 25 udanych z każdego klucza. Drugi klucz nie podwaja więc limitu. Szczegóły limitów są w cenniku.
Wygasanie. OWASP zaleca tworzyć sekrety tak, żeby „expire after a defined time where possible” (OWASP). Klucz z datą ważności po terminie przestaje działać sam, nawet jeśli wszyscy o nim zapomną. W naszym panelu przy tworzeniu klucza wybierasz ważność: bez daty, 30, 90 albo 365 dni. Klucz po terminie dostaje 401 API_KEY_EXPIRED — taki wynik dało zapytanie z kluczem testowym, któremu ustawiliśmy datę w przeszłości.
Jak wymienić klucz API bez przestoju i co zrobić po wycieku
Regularna wymiana klucza (rotacja) sprawia, że skradziony klucz działa krótko. OWASP: „You should regularly rotate secrets so that any stolen credentials will only work for a short time”, a sekrety niepotrzebne albo potencjalnie ujawnione trzeba unieważnić (OWASP). Google opisuje rotację jako trzy ruchy: utwórz nowy klucz, przełącz aplikację, usuń stary (Google Cloud). Klucz da się wymienić bez minuty przerwy, jeśli dostawca pozwala mieć dwa aktywne naraz — u nas do 10 aktywnych na konto:
Wymiana klucza API bez przestoju — i skrót na wypadek wycieku
pięć kroków w panelu DVN Links; kody odpowiedzi z lokalnej instancji
Źródło: OWASP Secrets Management Cheat Sheet; Google Cloud, API keys best practices; kody z lokalnej instancji, 21.10.2026
Opis figury
Oś czasu w pięciu krokach. 1. Utwórz nowy klucz; stary dalej działa, do 10 aktywnych kluczy na konto. 2. Podmień klucz w aplikacji, w menedżerze sekretów albo zmiennej na serwerze, i wdróż. 3. Patrz na Ostatnie użycie; gdy przy starym kluczu przestaje się zmieniać, nikt go już nie używa. 4. Wyłącz stary klucz; od tej chwili 401 INVALID_API_KEY, da się go włączyć z powrotem. 5. Usuń go po kilku dniach, gdy nic się nie zepsuło; usunięcia nie cofniesz. Przy wycieku: od razu krok 4, potem 1 i 2, i sprawdź, co zrobiono kluczem. Klucz z datą ważności po terminie: 401 API_KEY_EXPIRED.
Krok trzeci łatwo pominąć, a to on chroni przed przestojem. Kolumna „Ostatnie użycie” w panelu aktualizuje się przy każdym zapytaniu danym kluczem. Jeśli po wdrożeniu stary klucz nadal pokazuje „Dziś”, gdzieś jeszcze działa jakiś skrypt albo drugi serwer, o którym zapomniałeś. Wyłączenie zamiast usunięcia daje drogę powrotu: wyłączony klucz dostaje 401 INVALID_API_KEY, ale jednym przełącznikiem możesz go włączyć, jeśli coś przestanie działać.
Wyciek odwraca kolejność. Jeśli klucz trafił do publicznego repozytorium, na zrzut ekranu albo do wiadomości wysłanej nie tam, gdzie trzeba, nie czekaj z wymianą do wdrożenia nowego. Wyłącz go od razu — przerwa w integracji jest tańsza niż cudze zapytania na Twoim koncie. Potem utwórz nowy klucz, wdroż go i sprawdź, co działo się na koncie w czasie, gdy klucz był dostępny. Usunięcie pliku z repozytorium nie wystarczy, bo klucz zostaje w historii — trzeba go unieważnić.
Klucza nie wklejaj też na strony, do których prowadzi link z nieoczekiwanego e-maila „od dostawcy”. Prośba o klucz albo o zalogowanie się przez link z wiadomości to klasyczny phishing; jak ocenić taki link, zanim go klikniesz, opisuje tekst o bezpieczeństwie linków.
Najczęstsze pytania
Hasło programu do innego programu: długi, losowy ciąg znaków, który identyfikuje aplikację i jej konto u dostawcy. Kto go ma, działa w imieniu właściciela, dlatego chronisz go jak hasło.
W panelu dostawcy — nigdy samodzielnie. U nas: Panel → Ustawienia → Klucze API → „Utwórz klucz”, nazwa, ważność i skopiowanie klucza od razu, bo drugi raz go nie zobaczysz. API jest dostępne od planu Starter i w 7-dniowym okresie próbnym nowego konta. Pierwsze zapytanie z kluczem pokazuje poradnik o pierwszych krokach.
Nie zawsze. Klucz API jest długowieczny i przypisany do aplikacji; token dostępu OAuth zwykle żyje krótko i działa w imieniu użytkownika, w zakresie, na który ten się zgodził. Oba wysyła się często tym samym nagłówkiem Authorization: Bearer, bo oba są „bearer” — używa ich każdy, kto je ma.
Wyłączyć go od razu, utworzyć nowy, wdrożyć i sprawdzić, co działo się na koncie. Usunięcie klucza z kodu nie wystarczy — zostaje w historii Git.
Technicznie często się da, ale nie powinieneś: adres z kluczem zostaje w logach serwerów i w historii przeglądarki (RFC 6750 §5.3). W naszym API taki sposób jest wycofywany i odpowiedź dostaje nagłówki Deprecation i Warning.
Chcesz sprawdzić to w praktyce? Załóż konto, utwórz klucz w ustawieniach i wyślij pierwsze zapytanie — wszystkie punkty końcowe opisuje interaktywna dokumentacja /api/reference. Pełną listę możliwości znajdziesz na stronie funkcji.