KSeF błąd 401 – Co oznacza i jak naprawić?

Próbujesz wysłać fakturę do KSeF i zamiast potwierdzenia przyjęcia dostajesz odpowiedź: 401 Unauthorized. W programach do faktur ten sam błąd wygląda zwykle jak „Błąd komunikacji z serwerem KSeF 401” albo „Wymagane jest uwierzytelnienie”. Program do fakturowania pokazuje komunikat o błędzie autoryzacji, token się nie zgadza, albo sesja wygasła. Co to właściwie oznacza i – przede wszystkim – jak to naprawić?

Błąd 401 w KSeF to jeden z najczęściej występujących problemów technicznych, szczególnie po aktualizacjach systemu po stronie Ministerstwa Finansów lub przy pierwszej konfiguracji integracji. Dobra wiadomość: w zdecydowanej większości przypadków można go naprawić samodzielnie w kilka minut.

1. Co oznacza błąd 401 Unauthorized w KSeF?

Kod HTTP 401 Unauthorized to standardowy kod protokołu HTTP oznaczający problem z autoryzacją. Nazwa jest nieco myląca – „Unauthorized" dosłownie znaczy „nieautoryzowany", ale w praktyce chodzi o błąd uwierzytelnienia – system nie może potwierdzić Twojej tożsamości lub ważności Twojego dostępu.

Błąd 401 nie oznacza, że coś jest nie tak z Twoją fakturą. To problem z dostępem do systemu, nie z treścią dokumentu. Dopóki nie rozwiążesz problemu z autoryzacją, KSeF nie pozwoli Ci w ogóle wysłać faktury do weryfikacji.

• •token autoryzacyjny jest nieważny, wygasły lub błędnie wklejony
• •sesja API wygasła i trzeba ją ponownie otworzyć
• •logujesz się w złym kontekście (np. jako osoba fizyczna zamiast w kontekście NIP firmy)
• •token został wygenerowany w środowisku testowym i próbujesz go użyć w produkcji (lub odwrotnie)
• •oprogramowanie używa starego mechanizmu autoryzacji niekompatybilnego z aktualną wersją API KSeF

2. Błąd 401 a błąd 403 – kluczowa różnica

Wiele osób myli błąd 401 z błędem 403. To dwa różne problemy i mają różne rozwiązania.

3. Wszystkie przyczyny błędu 401 – od najczęstszych

Przyczyna #1: Nieaktualna wersja oprogramowania

To najczęstsza przyczyna błędu 401 po aktualizacjach KSeF. Ministerstwo Finansów regularnie aktualizuje API i wymagania bezpieczeństwa. Starsze wersje programów mogą używać metod autoryzacji lub adresów endpointów które przestały być akceptowane. Sprawdź: czy Twój program jest w najnowszej wersji.

Przyczyna #2: Token skopiowany z błędem

Token KSeF to ciąg 40 znaków. Jeden niewidoczny znak spacji na początku lub końcu powoduje błąd 401. Zdarza się gdy token jest kopiowany z emaila, dokumentu Word lub PDF które mogą dodać formatowanie. Sprawdź: usuń token z programu, skopiuj bezpośrednio z portalu MF i wklej ponownie.

Przyczyna #3: Wygasła sesja API

W integracji API KSeF działa dwupoziomowo: masz Token autoryzacyjny (40-znakowy z portalu MF) i accessToken sesji (JWT, generowany przy każdym logowaniu, wygasa po czasie). Jeśli sesja wygasła, aplikacja musi ponownie ją otworzyć. Sprawdź: czy program automatycznie odnawia sesję.

Przyczyna #4: Token z środowiska testowego w produkcji

KSeF ma środowisko testowe (ksef-demo.mf.gov.pl) i produkcyjne (ksef.mf.gov.pl). Token z jednego środowiska nie działa w drugim. Jeśli niedawno przenosiłeś się ze środowiska testowego – musisz wygenerować nowy token w środowisku produkcyjnym.

Przyczyna #5: Logowanie w złym kontekście

Możesz zalogować się do KSeF jako osoba fizyczna (na PESEL) lub w kontekście firmy (na NIP). Błąd 401 może oznaczać że próbujesz wykonać operację wymagającą kontekstu firmowego będąc zalogowanym jako osoba prywatna.

Przyczyna #6: Token unieważniony ręcznie

Ktoś z uprawnieniami do zarządzania tokenami (właściciel firmy, administrator) mógł unieważnić token na portalu MF. Zdarza się przy zmianach personalnych lub po podejrzanej aktywności. Sprawdź: na portalu MF w sekcji zarządzania tokenami czy token jest aktywny.

Przyczyna #7: Zmiany po stronie MF – świeże aktualizacje

MF może wprowadzić zmiany w API które producent oprogramowania jeszcze nie obsłużył. W takim przypadku błąd 401 może występować nawet przy poprawnym tokenie i aktualnej wersji. Sprawdź komunikaty od producenta – zazwyczaj aktualizacja pojawia się w ciągu kilku dni.

4. Czym jest token KSeF i jak działa autoryzacja?

Token autoryzacyjny KSeF to ciąg 40 znaków generowany przez portal Ministerstwa Finansów. Pełni rolę klucza dostępu dla aplikacji – zamiast wpisywać login i hasło przy każdej operacji, aplikacja używa tokenu który autoryzuje ją do działania w Twoim imieniu.

• •Wyświetla się tylko raz – po wygenerowaniu musisz go natychmiast skopiować. Portal MF nie pozwoli Ci go podejrzeć ponownie.
• •Jest powiązany z konkretnym NIP firmy – token wygenerowany dla firmy A nie zadziała dla firmy B.
• •Ma określony zakres uprawnień – możesz wygenerować token tylko do wystawiania, tylko do odbioru, lub do obu operacji.
• •Można go unieważnić – w każdej chwili możesz unieważnić stary token i wygenerować nowy.

5. Jak naprawić błąd 401 – instrukcja krok po kroku

Przejdź przez kroki po kolei – większość przypadków rozwiązuje się na kroku 1, 2 lub 3.

Krok 1: Zaktualizuj oprogramowanie

Przed czymkolwiek innym – sprawdź czy używasz najnowszej wersji programu do fakturowania. Wejdź na stronę producenta i porównaj wersję. Po instalacji uruchom program ponownie i sprawdź czy błąd nadal występuje.

Krok 2: Usuń i wklej token od nowa

• •W programie przejdź do ustawień KSeF / integracji
• •Wyczyść pole z tokenem całkowicie – zaznacz całą zawartość i usuń
• •Otwórz przeglądarkę i zaloguj się na ksef.mf.gov.pl
• •Przejdź do sekcji tokenów – znajdź swój aktywny token
• •Skopiuj token bezpośrednio z portalu – użyj przycisku kopiowania jeśli jest dostępny
• •Wróć do programu i wklej token w puste pole
• •Sprawdź czy przed ani po tekście tokenu nie ma spacji
• •Zapisz ustawienia i przetestuj połączenie

Krok 3: Wygeneruj nowy token

Jeśli kroki 1 i 2 nie pomogły – wygeneruj zupełnie nowy token. Procedurę opisujemy szczegółowo w sekcji 6 poniżej.

Krok 4: Sprawdź środowisko (testowe vs produkcyjne)

Upewnij się że program łączy się ze środowiskiem produkcyjnym KSeF. Środowisko produkcyjne: ksef.mf.gov.pl. Środowisko testowe: ksef-demo.mf.gov.pl. Token z portalu produkcyjnego nie zadziała w środowisku testowym i odwrotnie.

Krok 5: Sprawdź kontekst logowania

Na portalu MF zaloguj się i sprawdź w jakim kontekście jesteś. Jeśli wystawiasz faktury dla firmy – musisz być zalogowany w kontekście NIP tej firmy, nie jako osoba prywatna. Szczegóły opisujemy w sekcji 8.

Krok 6: Skontaktuj się z supportem programu

Jeśli wszystkie powyższe kroki nie pomogły – skontaktuj się z pomocą techniczną producenta. Podaj: pełną treść komunikatu błędu, kod serwisowy (jeśli widoczny), wersję programu i datę kiedy problem się pojawił.

6. Jak wygenerować nowy token KSeF na portalu MF

• •Profil Zaufany (ePUAP) lub e-dowód lub certyfikat kwalifikowany
• •Dostęp do portalu ksef.mf.gov.pl
• •NIP firmy dla której generujesz token
• •Bezpieczne miejsce do zapisania tokenu (wyświetla się tylko raz)

Procedura generowania tokenu – krok po kroku

• •Krok 1: Zaloguj się na portal KSeF – wejdź na ksef.mf.gov.pl przez Profil Zaufany, e-dowód lub certyfikat kwalifikowany.
• •Krok 2: Wybierz kontekst firmy – po zalogowaniu wybierz NIP firmy z listy podmiotów, nie działaj jako osoba prywatna.
• •Krok 3: Przejdź do zarządzania tokenami – w menu znajdź sekcję „Tokeny" lub „Zarządzanie tokenami".
• •Krok 4: Opcjonalnie unieważnij stary token – nie jest konieczne, ale dobra praktyka przy wymianie tokenów.
• •Krok 5: Generuj nowy token – kliknij „Generuj nowy token" i wybierz zakres uprawnień.
• •Krok 6: Skopiuj token natychmiast – system wyświetli go jednorazowo. Zapisz w menedżerze haseł.
• •Krok 7: Wklej token do programu – w ustawieniach KSeF, upewniając się że nie ma spacji.
• •Krok 8: Przetestuj połączenie – użyj opcji testowania lub wyślij fakturę testową.

7. Błędy przy kopiowaniu tokenu – co może pójść nie tak

Nieprawidłowe skopiowanie tokenu to jeden z najczęstszych powodów błędu 401. Token to 40 znaków i jeden dodatkowy, niewidoczny znak niszczy całą autoryzację.

• •Spacje na początku lub końcu – niewidoczne gołym okiem. Po wklejeniu ustaw kursor na początku pola i sprawdź czy jest tam spacja.
• •Złamanie linii – z dokumentu Word, PDF lub emaila może zawierać ukryty znak nowej linii. Zawsze kopiuj bezpośrednio z portalu MF.
• •Obcięcie tokenu – zbyt wąskie pole lub zaznaczenie tylko części tekstu. Token ma dokładnie 40 znaków – możesz zweryfikować wklejając do Notatnika.
• •Formatowanie z Worda – zamiana prostych myślników na typograficzne, cudzysłowów itp. Token kopiowany z dokumentu może zawierać różne znaki niż oryginał.

8. Logowanie w złym kontekście – częsty i mylący błąd

KSeF rozróżnia dwa konteksty działania: osoba fizyczna (na PESEL) i podmiot gospodarczy (na NIP firmy). Gdy właściciel JDG loguje się do KSeF jako osoba prywatna i próbuje wystawiać faktury firmowe – dostaje błąd 401.

Jak to sprawdzić i naprawić?

• •Po zalogowaniu na portal ksef.mf.gov.pl sprawdź prawy górny róg – powinien być widoczny NIP firmy, nie PESEL
• •Jeśli widzisz PESEL lub dane osobowe bez NIP – szukaj opcji „Zmień podmiot" lub „Działaj w imieniu"
• •Wybierz NIP firmy z listy podmiotów
• •Jeśli firma nie pojawia się na liście – musisz najpierw nadać sobie uprawnienia (patrz niżej)

Nadawanie uprawnień sobie – instrukcja

• •Zaloguj się na ksef.mf.gov.pl przez Profil Zaufany
• •Wybierz opcję „Zarządzanie uprawnieniami" lub „Nadaj uprawnienia"
• •Wybierz nadanie uprawnień dla osoby fizycznej – wpisz swój PESEL
• •Nadaj uprawnienia: wystawianie, odbiór, zarządzanie – zależnie od potrzeb
• •Potwierdź operację
• •Po nadaniu uprawnień będziesz mógł logować się w kontekście firmy i generować tokeny

9. Token autoryzacyjny vs sesja API – różnica dla deweloperów

Dla osób integrujących KSeF przez API ważne jest zrozumienie różnicy. Token autoryzacyjny (40 znaków z portalu MF) to Twój „klucz główny" – generujesz go raz, używasz do otwierania sesji. AccessToken sesji (JWT) to tymczasowy token generowany przez API przy każdej sesji – wygasa po kilkudziesięciu minutach.

Gdy accessToken JWT wygaśnie – API zwraca błąd 401. Rozwiązanie to nie generowanie nowego tokenu autoryzacyjnego, ale ponowne otwarcie sesji endpointem odświeżania.

Dobra praktyka przy integracji API

• •Wyślij żądanie do API
• •Jeśli odpowiedź 401 – otwórz nową sesję używając tokenu autoryzacyjnego
• •Ponów żądanie z nowym accessTokenem
• •Jeśli nadal 401 – token autoryzacyjny mógł wygasnąć lub być unieważniony – zaloguj błąd i powiadom administratora

10. Terminy ważności tokenów KSeF w 2026 roku

11. Błąd 401 w biurze rachunkowym – specyficzne przypadki

• •Klient odwołał token biura – klient zmienił biuro lub z innego powodu unieważnił token. Klient musi nadać nowe uprawnienia.
• •Biuro ma uprawnienia tylko do odbioru – token biura ma tylko InvoiceRead, próba wysyłania daje 401. Klient musi rozszerzyć zakres uprawnień.
• •Jeden token dla wielu klientów – token jest zawsze powiązany z konkretnym NIP. Biuro obsługujące 50 klientów potrzebuje 50 osobnych tokenów.

12. Jak zapobiegać błędowi 401 w przyszłości

• •Przechowuj token bezpiecznie – zapisz go natychmiast po wygenerowaniu w menedżerze haseł (Bitwarden, 1Password). Nigdy w zwykłym pliku tekstowym.
• •Aktualizuj oprogramowanie regularnie – sprawdzaj co miesiąc. Większość błędów 401 po aktualizacjach KSeF jest naprawiana przez producentów w kilka dni.
• •Monitoruj datę 31.12.2026 – sprawdź, czy rozporządzenie zostało zmienione zgodnie z zapowiedzią MF o utrzymaniu tokenów. Jeśli nie, przed tą datą potrzebny jest certyfikat KSeF.
• •Testuj połączenie przed ważnymi wysyłkami – przed końcem miesiąca przetestuj jedno wysłanie faktury. Jeśli coś nie działa – masz czas na naprawę.
• •Waliduj faktury lokalnie – wyeliminuj jeden problem naraz: najpierw sprawdź czy faktura jest technicznie poprawna, potem diagnozuj token.