Token KSeF: co to jest, jak go wygenerować i do kiedy działa
Token KSeF to metoda uwierzytelnienia z zapisanym w niej zakresem uprawnień. Pokazujemy, kiedy jest potrzebny, jak go wygenerować i nazwać, czym różni się od certyfikatu i do kiedy pozostaje ważny.
Token KSeF to wygenerowany przez system ciąg znaków alfanumerycznych, przypisany do konkretnego podatnika i do konkretnego zakresu uprawnień. Służy do uwierzytelnienia i autoryzacji w KSeF.
Generujesz go raz, po zalogowaniu się podpisem albo pieczęcią. Od tej pory Twój program księgowy loguje się nim sam i nie podpisujesz każdej wysyłki.
Poniżej: kiedy token jest potrzebny, jak go wygenerować, jak go nazwać, czym różni się od certyfikatu i do kiedy działa.
Czym jest token KSeF i do czego służy
Token jest narzędziem służącym do uwierzytelnienia i autoryzacji w KSeF. Generuje go podatnik na określony zakres uprawnień, po uwierzytelnieniu się w systemie.
Do wygenerowania tokena uwierzytelnisz się Węzłem krajowym, kwalifikowanym podpisem elektronicznym, kwalifikowaną pieczęcią elektroniczną albo certyfikatem KSeF.
Definicję i tę listę metod podaje Podręcznik KSeF 2.0 cz. I w rozdziale 2.4. Token działa w sesji interaktywnej i we wsadowej.
W KSeF nie ma loginu i hasła
System opiera się na modelu poświadczeń. Każde wejście wymaga uwierzytelnienia — nie ma konta z hasłem, które program mógłby po prostu zapamiętać.
Token wypełnia dokładnie tę lukę. Zastępuje powtarzane logowanie podpisem tam, gdzie logować ma się program, a nie człowiek.
Tokenem nie zalogujesz się do Aplikacji Podatnika
To wyjątek, który zaskakuje najczęściej. Aplikacja Podatnika KSeF nie przyjmuje tokena jako metody uwierzytelnienia — token jest przeznaczony do API.
Do samej Aplikacji logujesz się Węzłem krajowym albo certyfikatem kwalifikowanym. Token wpisujesz dopiero w programie, który wysyła faktury.
Kto generuje token i czyje dane zobaczy KSeF
Token może być wygenerowany dla osoby fizycznej albo dla podmiotu, który osobą fizyczną nie jest — na przykład dla spółki.
Jeśli spółka uwierzytelni się kwalifikowaną pieczęcią i wygeneruje token na swoje uprawnienia, po zalogowaniu się nim system widzi spółkę, a nie konkretnego człowieka.
Jeśli token wygeneruje pracownik na swój numer PESEL, działając w kontekście spółki, KSeF przy fakturze pokaże dane tej osoby fizycznej.
Przy integracji ma to skutek praktyczny: token wygenerowany na dane pracownika przestanie działać w dniu, w którym odbierzesz mu uprawnienia.
Kiedy potrzebujesz tokena, a kiedy nie
Token nie jest obowiązkowy. To jedna z dopuszczalnych metod uwierzytelnienia i potrzebujesz jej wtedy, gdy plik do KSeF wysyła program, a nie Ty ręcznie.
Jeśli wystawiasz faktury w bezpłatnej Aplikacji Podatnika i logujesz się do niej podpisem, token nie jest Ci do niczego potrzebny.
Jeśli faktury wysyła program księgowy, ERP albo system do obsługi zamówień, potrzebujesz tokena albo certyfikatu KSeF typu 1. Punkt wyjścia opisujemy w tekście o fakturze ustrukturyzowanej.
Podpis zaufany w programie komercyjnym nie wystarczy
Podpisu Zaufanego można użyć do logowania i autoryzacji w KSeF, ale tylko w aplikacjach przygotowanych przez organy publiczne.
W programie komercyjnym i tak trzeba uwierzytelnić się inaczej: podpisem kwalifikowanym, pieczęcią, tokenem albo certyfikatem KSeF. Ministerstwo odpowiada na to wprost w pytaniach i odpowiedziach KSeF 2.0.
Jak wygenerować token KSeF krok po kroku
Token wygenerujesz w Aplikacji Podatnika KSeF albo w programie finansowo-księgowym zintegrowanym z API KSeF. Ścieżka w Aplikacji ma cztery kroki.
Najpierw nawiązujesz sesję Węzłem krajowym lub certyfikatem kwalifikowanym. Potem wybierasz w menu Tokeny, a w nim Generuj token.
Wpisujesz nazwę własną tokena, zaznaczasz uprawnienia i klikasz Generuj token. Numer skopiujesz z ekranu potwierdzenia.
Tokeny wygenerowane w KSeF 1.0 nie są kompatybilne z KSeF 2.0 i nie zostały do niego przeniesione. Jeśli integrację ustawiałeś przed lutym 2026 r., musiałeś wygenerować nowy.
Token zobaczysz tylko raz
Aplikacja Podatnika ze względów bezpieczeństwa wyświetla wygenerowany ciąg znaków jednorazowo. Nie ma ekranu, na którym podejrzysz go później.
Zapisz go od razu poza Aplikacją: w firmowym menedżerze haseł albo bezpośrednio w polu konfiguracji programu, który ma go używać.
Jeśli go zgubisz, jedyne wyjście to wygenerować nowy i unieważnić stary. Odzyskać się go nie da.
Ile tokenów możesz mieć
Nie są przewidziane ograniczenia systemowe co do liczby posiadanych i używanych tokenów.
To ważniejsze, niż się wydaje. Dzięki temu możesz rozdzielić tokeny po integracjach, zamiast wpisywać jeden i ten sam wszędzie.
Jak wygląda token i jak go nazwać
Sam token to ciąg znaków alfanumerycznych, bez znaków interpunkcyjnych. Patrząc na niego, nie odczytasz ani komu go wydano, ani po co.
Czytelna jest wyłącznie nazwa własna, którą wpisujesz przy generowaniu. To pole robi całą pracę porządkową.
Na liście tokenów widzisz nazwę, twórcę tokena, datę aktywacji i datę ostatniego użycia. Nie widzisz, w którym systemie token faktycznie siedzi.
Konwencja nazw, która przetrwa audyt
Ministerstwo pokazuje ten mechanizm na przykładzie spółki, która wygenerowała sześć tokenów i nazwała je „Przedstawiciel handlowy – rejon 1” i tak dalej.
U sprzedawcy internetowego zasada jest ta sama, tylko rejony zamieniasz na systemy. Nazwa ma powiedzieć, gdzie token pracuje, po co i od kiedy.
Dzięki temu po roku wiesz, który token unieważnić po zmianie dostawcy oprogramowania, a którego nie ruszać.
Zakres uprawnień zapisany w tokenie
Token zawiera w sobie uprawnienia podatnika, deklarowane w momencie jego generowania. To jego najważniejsza cecha i źródło większości pomyłek.
W Aplikacji Podatnika do wyboru są: wystawianie faktur, przeglądanie faktur, przeglądanie uprawnień, zarządzanie uprawnieniami, zarządzanie jednostkami podrzędnymi oraz przeglądanie historii sesji.
Możesz wygenerować jeden token na wszystkie swoje uprawnienia albo kilka tokenów, każdy na inny zakres. Decyzja należy do tego, kto go generuje.
Nie przypiszesz jednak do tokena uprawnienia, którego w tym momencie nie masz. Sam model uprawnień w KSeF to osobny temat, który rozbieramy w oddzielnym tekście.
Uprawnienia w KSeF nadaje się konkretnym osobom i podmiotom, a nie systemom. Dlatego jednostką, którą wpisujesz do integracji, jest token, a nie konto techniczne programu.
Tokena nie da się zaktualizować
Wygenerowane tokeny nie podlegają aktualizacji. Jeśli token ma zapisane wystawianie faktur, nie dopiszesz do niego dostępu do faktur.
Zostają dwie drogi: wygenerować drugi token na brakujące uprawnienie albo unieważnić stary i wydać nowy na pełny zakres.
Jeden token, jeden kontekst
Token wygenerowany we własnym kontekście działa tylko w tym kontekście. Token wygenerowany w kontekście spółki, od której masz uprawnienia, działa tylko tam.
Księgowa obsługująca trzy firmy potrzebuje więc trzech tokenów, po jednym na kontekst. Certyfikat zachowuje się tu inaczej.
Token a certyfikat KSeF — czym się różnią
Obie metody działają równolegle i obie służą do uwierzytelnienia. Nie są jednak funkcjonalnie równoważne i to nie jest niuans.
Token jest nośnikiem uprawnień. Certyfikat typu 1 nie — po zalogowaniu się nim system bierze uprawnienia powiązane z identyfikatorem podatkowym zapisanym na certyfikacie.
Stąd dwie praktyczne konsekwencje. Certyfikat działa w wielu kontekstach, token w jednym. Certyfikat ma datę ważności, token nie.
Oba typy certyfikatu i ścieżkę wniosku opisujemy osobno w tekście o certyfikacie KSeF.
Token KSeF — do kiedy jest ważny
To pytanie ma dwie odpowiedzi, bo dotyczy dwóch różnych rzeczy: dostępności samej metody i ważności pojedynczego tokena.
Według pierwotnych założeń tokeny miały być dostępne jako metoda uwierzytelnienia do końca 2026 r. Ministerstwo Finansów zdecydowało jednak o ich utrzymaniu bezterminowo i zapowiedziało nowelizację rozporządzenia.
Potwierdza to strona Ministerstwa o certyfikatach KSeF, a drugi raz — odpowiedź na pytanie o wygaśnięcie tokenów z końcem 2026 r.
Dla sprzedawcy oznacza to jedno: jeśli Twoja integracja działa na tokenie, nie ma terminu, do którego musisz przejść na certyfikat.
Pojedynczy token nie ma daty ważności
KSeF nie określa czasu, w jakim token jest ważny. Wygenerowany token pozostaje ważny do czasu jego unieważnienia przez użytkownika.
Nie musisz więc pilnować kalendarza tak, jak przy certyfikacie, który wygasa najpóźniej po dwóch latach.
Odebranie uprawnień to nie unieważnienie
Jeśli komuś odebrano uprawnienia zapisane w tokenie, system nie unieważnia samego tokena. Skutek jest inny: nie da się nim uwierzytelnić.
Po ponownym nadaniu tego uprawnienia token znów zadziała. Warto to wiedzieć, zanim ktoś zacznie generować nowe tokeny, bo „stary padł”.
Token w środowisku testowym
KSeF ma osobne środowiska: produkcyjne, testowe i przedprodukcyjne demo. Są od siebie logicznie i technicznie odseparowane.
Token wygenerowany w środowisku testowym nie zadziała na produkcji. Ministerstwo przypomina, że w środowisku produkcyjnym obowiązują wyłącznie klucze, certyfikaty i tokeny pochodzące z produkcji.
To jedna z najczęstszych przyczyn komunikatu „token nie działa” na starcie wdrożenia. Objaw jest techniczny, przyczyna organizacyjna. Zasady opisuje komunikat Ministerstwa dla integratorów.
W testowej wersji Aplikacji Podatnika możesz posługiwać się dowolnymi, fikcyjnymi danymi, a dane są okresowo usuwane. To właściwe miejsce na testy integracji.
Bezpieczeństwo: przechowywanie, rotacja, unieważnienie
Token to bezpieczna metoda uwierzytelniania pod jednym warunkiem: nie jest ujawniany osobom postronnym. Ministerstwo apeluje, żeby traktować go jak dane do bankowości elektronicznej.
Niedopuszczalne jest, żeby osoba fizyczna wygenerowała token, a potem przekazała go innym osobom do uwierzytelniania się w KSeF.
Gdzie trzymać token
Menedżer haseł albo pole konfiguracji w systemie, który go używa. Nigdy arkusz, mail ani czat — apel Ministerstwa o traktowanie tokenów jak danych szczególnie wrażliwych znajdziesz w komunikacie o generowaniu tokenów.
Do integracji wpisujesz go raz. Jeśli ktoś prosi Cię o token „do sprawdzenia”, to ta sama kategoria prośby, co o kod z SMS-a.
Rotacja bez przestoju w wysyłce
Ponieważ liczba tokenów nie jest ograniczona, wymianę zrobisz bez przerwy w pracy. Wygeneruj nowy, wpisz w integracji, sprawdź jedną fakturę, unieważnij stary.
Unieważnić token może ten, kto go wygenerował, albo osoba z uprawnieniem do zarządzania uprawnieniami. Robi się to na liście tokenów lub przez API.
Rotację zaplanuj przy każdej zmianie: odejście pracownika, zmiana dostawcy oprogramowania, koniec współpracy z biurem rachunkowym.
Co zrobić, gdy token przestaje działać
Token nie wygasa, więc „przestał działać” prawie nigdy nie znaczy „stracił ważność”. Zwykle znaczy jedno z pięciu.
Sprawdź w tej kolejności
- Czy token pochodzi ze środowiska produkcyjnego, a nie z testowego.
- Czy kontekst jest ten sam — token działa tylko tam, gdzie go wygenerowano.
- Czy uprawnienia zapisane w tokenie nie zostały w KSeF odebrane.
- Czy token nie został unieważniony — na liście tokenów już go wtedy nie ma.
- Czy zakres nie jest za wąski — wystawianie faktur to nie dostęp do faktur.
Data ostatniego użycia na liście tokenów rozstrzyga pierwszą wątpliwość. Jeśli jest pusta, ten token nigdy nie uwierzytelnił się w systemie.
Jeśli żaden z tych punktów nie wyjaśnia problemu, zajrzyj na komunikaty techniczne KSeF, zanim zaczniesz generować kolejny token.
Czym uwierzytelnia się integracja easySales
Nasza integracja z KSeF loguje się tokenem i przesyła faktury w trybie online. Token wklejasz raz w ustawieniach i nie wracasz do niego.
Zakres tokena dobierz do tego, co program ma robić. Wysyłanie faktur to uprawnienie do wystawiania, a pobranie UPO — przeglądanie historii sesji.
Zakres naszej obsługi KSeF opisuje strona integracji, a same numery i poświadczenia — tekst o numerze KSeF i UPO.
Czy dany obowiązek i tryb dotyczą Twojej sprzedaży, ustal ze swoim biurem rachunkowym. Tu opisujemy wyłącznie to, czym token jest technicznie i czego wymaga integracja.
