Uwierzytelnianie KSeF 2.0 dla deweloperów: przewodnik 2026

Uwierzytelnianie w KSeF 2.0 składa się z dwóch warstw: najpierw potwierdzasz tożsamość podpisem XAdES albo dotychczasowym tokenem KSeF, a potem wywołujesz chronione endpointy za pomocą otrzymanego tokena JWT. Zgodnie z przepisami obowiązującymi 28 sierpnia 2026 r. metoda z tokenem kończy się 31 grudnia 2026 r. Nowe integracje produkcyjne powinny korzystać z certyfikatów KSeF typu 1.

Ten przewodnik został zweryfikowany 28 sierpnia 2026 r. na podstawie dokumentacji Ministerstwa Finansów i oficjalnego repozytorium KSeF API. API nadal się zmienia, dlatego oficjalny changelog traktuj jak część zależności produkcyjnych.

Jak działa uwierzytelnianie w KSeF 2.0?

KSeF 2.0 oddziela uwierzytelnienie od sesji fakturowych. Najpierw ustalasz, kto wywołuje API i w kontekście którego podatnika. Dopiero po uzyskaniu accessToken otwierasz sesję interaktywną albo wsadową, wysyłasz faktury, pobierasz metadane lub dokumenty UPO.

W tym procesie występują cztery rodzaje danych uwierzytelniających. Ich pomylenie odpowiada za większość błędów wdrożeniowych:

Oficjalny przewodnik po uwierzytelnianiu opisuje ostatnią parę jako tokeny JWT wydawane po pomyślnym zakończeniu operacji asynchronicznej. Token dostępu trafia do nagłówka Authorization: Bearer .... Nie jest tym samym obiektem co starszy, długotrwały token KSeF.

Kontekst i tożsamość to dwie różne rzeczy

Każde logowanie odpowiada na dwa pytania:

1. W jakim kontekście będzie działać sesja? Najczęściej chodzi o firmę identyfikowaną numerem NIP, ale KSeF obsługuje też inne identyfikatory kontekstu.
2. Czyja tożsamość potwierdza logowanie? Może to być firma, osoba identyfikowana numerem PESEL lub NIP albo tożsamość powiązana z odciskiem certyfikatu.

KSeF sprawdza, czy uwierzytelniany podmiot ma przynajmniej jedno aktywne uprawnienie w wybranym kontekście. Sam ważny certyfikat nie wystarcza. Ma to znaczenie, gdy biuro rachunkowe lub pracownik obsługuje kilka firm: jeden certyfikat tożsamości może działać w wielu kontekstach, ale w każdym obowiązują inne uprawnienia.

Którą metodę uwierzytelniania KSeF wybrać w 2026 roku?

Dla nowej integracji produkcyjnej wybierz XAdES z certyfikatem KSeF typu 1 przeznaczonym do uwierzytelniania. Obsługę dotychczasowych tokenów KSeF zachowaj wyłącznie jako rozwiązanie przejściowe. Obowiązujące rozporządzenie dopuszcza tę metodę do 31 grudnia 2026 r., a aktualne materiały Ministerstwa wskazują, że od 1 stycznia 2027 r. pozostaną certyfikaty.

Ten termin wymaga zastrzeżenia. W czerwcu 2026 r. Ministerstwo zaproponowało przedłużenie działania tokenów KSeF oraz wprowadzenie krótszej ważności i mechanizmu odnawiania. Na dzień weryfikacji artykułu jest to propozycja konsultacyjna, nie uchwalona zmiana. Dopóki rozporządzenie się nie zmieni, planuj pracę według wiążącego terminu.

Rozróżnienie pochodzi wprost z podręcznika KSeF 2.0 Ministerstwa Finansów: certyfikat przenosi tożsamość, ale nie uprawnienia KSeF. Token KSeF zawiera ich podzbiór i działa tylko w jednym kontekście.

Nie używaj certyfikatu offline do uwierzytelniania

KSeF wydaje dwa rodzaje certyfikatów o odmiennym przeznaczeniu:

• Authentication podpisuje żądanie logowania.
• Offline potwierdza autentyczność wystawcy i integralność faktury w trybie offline.

Certyfikat Offline nie służy do uwierzytelniania wywołań API. Oficjalna dokumentacja certyfikatów ostrzega też przed używaniem certyfikatu uwierzytelniającego do podpisywania dowodów dla faktur offline. Przechowuj i opisuj oba klucze prywatne oddzielnie, żeby wdrożenie nie wybrało niewłaściwego.

Jak wdrożyć uwierzytelnianie certyfikatem?

Uwierzytelnienie certyfikatem to asynchroniczny proces challenge-response. Klient podpisuje XML lokalnie, wysyła go, sprawdza status operacji, a następnie tylko raz wymienia token tymczasowy.

1. Pobierz challenge

Wywołaj POST /auth/challenge. Zachowaj wartość challenge i timestamp. Challenge jest ważny przez 10 minut, wiąże kolejne żądanie ze świeżą próbą uwierzytelnienia i chroni przed ponownym użyciem starego dokumentu. Dla każdej próby pobieraj nowy, zamiast przechowywać go w cache.

2. Zbuduj AuthTokenRequest

Przygotuj żądanie XML z następującymi polami:

• challenge,
• typem i wartością identyfikatora kontekstu,
• typem identyfikatora uwierzytelnianego podmiotu,
• opcjonalnym AuthorizationPolicy, który ogranicza dozwolone adresy IPv4, zakresy lub maski.

Jeśli certyfikat zawiera NIP firmy, podmiot może uwierzytelnić się bezpośrednio. Gdy osoba podpisuje żądanie w imieniu firmy, KSeF odczytuje jej identyfikator z certyfikatu i sprawdza uprawnienia w kontekście firmy. Dla certyfikatów kwalifikowanych bez NIP lub PESEL może być potrzebny uprawniony odcisk certyfikatu.

3. Utwórz prawidłowy podpis XAdES

Podpisz XML wybranym certyfikatem tożsamości i jego kluczem prywatnym. Nie zakładaj, że stary przykład dla KSeF 1.0 nadal przejdzie walidację. API 2.1.0 zaostrzyło wymagania XAdES, a aktualne reguły obowiązują już we wszystkich środowiskach, co opisuje changelog KSeF API. Bieżące wymagania XAdES dopuszczają podpisy enveloped i enveloping, odrzucają detached oraz określają minimalne rozmiary kluczy RSA i EC.

Ministerstwo utrzymuje klientów referencyjnych w C# i Javie. Nawet jeśli aplikacja powstaje w innym języku, ich testy są przydatnymi przykładami serializacji XML, identyfikatorów certyfikatu i składania podpisu.

4. Wyślij żądanie i sprawdzaj status

Wyślij podpisany XML do POST /auth/xades-signature. Poprawna odpowiedź zawiera:

• referenceNumber, czyli identyfikator operacji asynchronicznej;
• authenticationToken, czyli tymczasowy JWT przeznaczony tylko dla tej operacji.

Sprawdzaj GET /auth/{referenceNumber} z tokenem tymczasowym. Ustaw rozsądny interwał i podziel odpowiedzi na trzy grupy: przetwarzanie trwa, zakończenie sukcesem oraz błąd końcowy. Nieprawidłowy podpis, problem z certyfikatem, brak uprawnień lub blokada bezpieczeństwa nie są przejściowymi błędami sieci. Nieskończone ponawianie tego samego wadliwego dokumentu jedynie zasłania przyczynę.

5. Wymień token tylko raz

Po pomyślnym uwierzytelnieniu wywołaj POST /auth/token/redeem z tokenem tymczasowym. KSeF zwraca accessToken i refreshToken. Wymiana jest jednorazowa. Dokumentacja uwierzytelniania wskazuje, że ponowne użycie tego samego authenticationToken kończy się HTTP 400.

Skrócony schemat implementacji wygląda tak:

challenge = POST /auth/challenge
request = build_auth_xml(challenge, context, subject, allowed_ips)
signed_xml = xades_sign(request, identity_certificate, private_key)

operation = POST /auth/xades-signature(signed_xml)
status = poll GET /auth/{operation.referenceNumber}
  Authorization: Bearer {operation.authenticationToken}

tokens = POST /auth/token/redeem
  Authorization: Bearer {operation.authenticationToken}

call protected endpoints with tokens.accessToken
refresh before accessToken.exp with tokens.refreshToken

6. Otwórz osobną sesję fakturową

Uwierzytelnienie nie otwiera sesji fakturowej. Po uzyskaniu ważnego tokena dostępu użyj go do wywołania POST /sessions/online albo POST /sessions/batch. KSeF 2.0 celowo rozdziela te zagadnienia. Jedna sesja uwierzytelnienia może więc autoryzować więcej niż pojedyncze otwarcie sesji, z którym wiązały ją starsze integracje.

Co zrobić, jeśli nadal uwierzytelniasz się tokenem KSeF?

Starsza ścieżka zaczyna się od tego samego POST /auth/challenge, ale nie podpisuje XML. Zbuduj {tokenKSeF}|{timestampMs} z sekretu i timestampa challenge, zaszyfruj całość aktualnym kluczem publicznym KSeF przy użyciu RSA-OAEP z SHA-256/MGF1, a wynik Base64 wyślij do POST /auth/ksef-token razem z challenge, kontekstem i wybranym publicKeyId.

Klucze szyfrujące pobieraj z GET /security/public-key-certificates. Nie wpisuj jednego klucza na stałe w kodzie. Oficjalny przewodnik po rotacji kluczy opisuje rotację planowaną i awaryjną. Gdy KSeF odrzuci wycofany lub nieznany identyfikator klucza, pobierz świeży zestaw i ponów operację z nowym challenge.

Dalsze sprawdzanie statusu i jednorazowa wymiana wyglądają tak samo jak w ścieżce XAdES. Sam token KSeF nigdy nie powinien trafić do logów. To główny sekret tej metody, a nie tymczasowy authenticationToken czy późniejszy JWT dostępu.

Jak bezpiecznie obsługiwać access token i refresh token?

Oba zwracane JWT są danymi uwierzytelniającymi, a nie niewinnymi metadanymi sesji. Token dostępu żyje krótko, lecz pozostaje użyteczny do czasu exp, nawet jeśli administrator zmieni w tym czasie uprawnienia podmiotu. Dopiero nowy token dostępu uzyskany przez odświeżenie zawiera aktualne role i uprawnienia.

W kliencie wprowadź następujące zabezpieczenia:

1. Czytaj exp, nie wpisuj na stałe domniemanego TTL. Odświeżaj z zapasem i jitterem, żeby wszystkie workery nie robiły tego w tej samej sekundzie.
2. Jedno odświeżenie dla danego zestawu danych. Gdy kilka workerów zauważy wygaśnięcie, tylko jeden powinien odnowić token i udostępnić wynik. Równoległa burza żądań nie poprawia dostępności.
3. Nigdy nie loguj bearer tokenów. Redaguj nagłówki Authorization, treść odpowiedzi endpointów tokenowych, payloady wyjątków i atrybuty trace’ów.
4. Nie trzymaj refresh tokenów w pamięci przeglądarki. Integracja serwerowa powinna przechowywać je w szyfrowanym magazynie, dostępnym tylko dla potrzebnego workera.
5. Błąd odświeżenia oznacza ponowne uwierzytelnienie. Wygasły lub nieprawidłowy refresh token powinien uruchomić ścieżkę certyfikatu, a nie nieskończoną pętlę.
6. Pilnuj czasu serwera. Rozjazd zegarów w pobliżu exp wywołuje sporadyczne błędy autoryzacji. Monitoruj synchronizację i odnawiaj token wcześniej.

Oficjalny przewodnik mówi o ważności access tokena liczonej w minutach oraz o refresh tokenie działającym do siedmiu dni. To granice implementacyjne, nie powód, żeby kopiować stałą liczbową z artykułu. Źródłem prawdy są JWT i aktualny kontrakt API.

Jak uprawnienia współdziałają z certyfikatami KSeF?

Certyfikat KSeF potwierdza tożsamość, ale nie jest kluczem do wszystkiego. Dokumentacja certyfikatów wyraźnie mówi, że certyfikat nie należy do konkretnego kontekstu i nie zawiera uprawnień KSeF. System sprawdza je po stronie serwera dla podmiotu i kontekstu wskazanych w żądaniu.

Taki model porządkuje dostęp:

• wydaj certyfikat osobie lub podmiotowi obsługującemu integrację;
• w każdym kontekście podatnika nadaj tylko niezbędne uprawnienia;
• podczas konfiguracji i diagnostyki pytaj API o faktyczny zestaw uprawnień;
• po zakończeniu współpracy odbieraj uprawnienia bez niepotrzebnego unieważniania certyfikatu tożsamości wszędzie;
• unieważnij certyfikat, jeśli wyciekł klucz prywatny albo sama tożsamość nie powinna już być zaufana.

Worker, który wyłącznie wysyła faktury, powinien zacząć od InvoiceWrite. Dodaj InvoiceRead tylko wtedy, gdy ten sam proces naprawdę pobiera lub wyszukuje faktury. Nie dawaj CredentialsManage rutynowym workerom fakturowym. Oficjalny przewodnik po uprawnieniach udostępnia zapytania o bieżące uprawnienia i role. Są pewniejsze niż wnioskowanie na podstawie logowania, które udało się kilka miesięcy wcześniej.

Warto podkreślić jedną pułapkę: żądanie uwierzytelnienia XAdES nie ma pola requestedPermissions, które zamieniałoby szeroko uprawnioną tożsamość w wąsko ograniczoną sesję certyfikatu. Jeśli uwierzytelnia się Owner, uzyskany dostęp może odzwierciedlać jego aktualne prawa. Minimalne uprawnienia zaczynają się więc od osoby lub podmiotu i nadanych im praw po stronie serwera, a nie od pliku certyfikatu. Opcjonalna polityka IP ogranicza miejsce użycia tokena, ale nie listę dostępnych operacji.

Unieważnienie nie działa natychmiast dla każdego typu danych

Projektując obsługę incydentu, uwzględnij dwa efekty czasowe:

• Unieważnienie certyfikatu KSeF typu 1 używanego przez aktywną sesję kończy tę sesję, zgodnie z podręcznikiem Ministerstwa.
• Odebranie uprawnienia nie przepisuje wstecz wydanego accessToken. Token może działać do exp, a dopiero odświeżenie pobiera aktualne uprawnienia.

W razie pilnego incydentu unieważnij przejęty certyfikat i zatrzymaj lokalnego workera. Przy zwykłym odejściu użytkownika odbierz uprawnienia, usuń zapisany refresh token z własnego systemu i uwzględnij krótki czas do wygaśnięcia access tokena. Loguj podmiot, kontekst, czas wydania tokena i numer seryjny certyfikatu, ale nigdy wartość tokena ani klucz prywatny.

Co zmienia się między TEST, DEMO i produkcją?

Kod uwierzytelnienia powinien być taki sam w każdym środowisku, ale założenia dotyczące zaufania już nie.

TEST dopuszcza certyfikaty samopodpisane. Ta wygoda zmienia granicę danych: oficjalny opis środowisk ostrzega, że kilku integratorów może uwierzytelnić się w kontekście tej samej firmy testowej. Używaj losowych numerów NIP i syntetycznych faktur. Nigdy nie wysyłaj do TEST prawdziwej tożsamości klienta, jego adresu, faktury ani produkcyjnych danych uwierzytelniających.

Nie przenoś samopodpisanego certyfikatu z TEST do DEMO ani na produkcję. W DEMO zweryfikuj prawdziwą ścieżkę certyfikatu: łańcuch zaufania, dane CSR, wczytywanie sekretów, alerty o wygaśnięciu oraz rotację z okresem, w którym stary i nowy certyfikat działają równolegle.

Co przenieść przed obecnym terminem na 2027 rok?

Jeśli integracja nadal zaczyna od tokena KSeF, zgodnie z obecnymi przepisami zakończ wdrożenie certyfikatów przed końcem 2026 r. Proponowane przedłużenie może zmienić datę, ale nie powinno zmieniać architektury nowej integracji. Najbezpieczniejsza kolejność obejmuje również operacje, nie tylko kryptografię.

1. Zrób inwentaryzację tokenów KSeF: właściciel, kontekst, uprawnienia, ostatnie użycie i usługa, która z nich korzysta.
2. Wydaj certyfikaty KSeF typu 1 właściwym osobom lub podmiotom.
3. W TEST wdroż challenge XAdES, sprawdzanie statusu, wymianę i odświeżanie tokenów.
4. Uruchom ścieżkę certyfikatu w DEMO z magazynem kluczy i polityką sieciową zbliżoną do produkcji.
5. Włącz uwierzytelnianie certyfikatem na produkcji w ramach kontrolowanego wdrożenia.
6. Porównaj działające konteksty i faktyczne uprawnienia starej oraz nowej ścieżki.
7. Przenieś cały ruch, sprawdź przynajmniej jedną pełną rotację i scenariusz awarii, a potem unieważnij stare tokeny KSeF.

Nie czekaj do grudnia, żeby odkryć, że proces zależy od pieczęci kwalifikowanej dostępnej tylko jednej osobie, dane CSR się nie zgadzają albo HSM nie potrafi przygotować wymaganego podpisu XAdES. Wydawanie certyfikatu jest asynchroniczne, certyfikaty wygasają, a uporządkowanie odpowiedzialności operacyjnej zwykle trwa dłużej niż napisanie kodu do endpointu.

Jak Kit podchodzi do uwierzytelniania KSeF?

Integracja KSeF dla Stripe przekształca sfinalizowane faktury Stripe do FA(3), wysyła je do KSeF i zachowuje wynikające z tego dowody w procesie rozliczeniowym. Praktyka potwierdza architekturę opisaną w tym przewodniku: dane tożsamości, kontekst podatnika, uprawnienia, krótkotrwały dostęp do API, sesje fakturowe i pobieranie UPO to oddzielne stany. Tak też powinny wyglądać w kodzie.

Standard jest prosty. Certyfikaty służą do potwierdzania tożsamości, uprawnienia do autoryzacji, JWT do ograniczonego czasowo dostępu do API, a każda operacja asynchroniczna powinna mieć własny rekord. Zobacz też szersze podejście Kit do bezpieczeństwa, śledź changelog KSeF, testuj rotację przed wygaśnięciem i potraktuj obecny termin na 2027 r. jako kamień milowy migracji, nie noworoczny incydent.