Token KSeF to ciąg znaków, który generujesz raz w Aplikacji Podatnika MF i wpisujesz w programie do faktur — od tej chwili program wysyła i odbiera faktury automatycznie bez ręcznego logowania. Sprawdź jak wygenerować token, jakie ma uprawnienia, czym różni się od certyfikatu KSeF i jak go bezpiecznie przechowywać.
Czym jest token KSeF i do czego służy
Token KSeF to jednorazowo wygenerowany ciąg znaków (tekstowy klucz API), który Aplikacja Podatnika MF wydaje podatnikowi jako „przepustkę” dla oprogramowania. Wpisujesz go w ustawieniach programu do fakturowania raz — i od tej chwili program może samodzielnie komunikować się z KSeF: wysyłać faktury, pobierać faktury kosztowe, sprawdzać status dokumentów.
Token rozwiązuje fundamentalny problem integracji: programy nie mogą logować się do KSeF przez przeglądarkę z kodem SMS za każdym razem, gdy chcą wysłać fakturę. Token jest odpowiednikiem „klucza API” znany z innych systemów SaaS — raz skonfigurowany, działa w tle bez angażowania użytkownika.
Różnica między tokenem a certyfikatem KSeF: token to ciąg znaków tekstowych — wklejasz go w pole tekstowe w ustawieniach. Certyfikat KSeF to plik kryptograficzny (.p12), który instalujesz w systemie lub programie. Token używany jest przede wszystkim do trybu online (komunikacja API przez sieć), certyfikat — w trybie offline24 (wystawianie faktur bez internetu). Szczegóły o certyfikacie opisuje artykuł o certyfikacie KSeF.
Jak wygenerować token KSeF — krok po kroku
- Krok 1 — Zaloguj się do Aplikacji Podatnika MF (app.ksef.mf.gov.pl) profilem zaufanym, podpisem kwalifikowanym lub pieczęcią kwalifikowaną.
- Krok 2 — Przejdź do sekcji „Zarządzanie dostępem” → „Tokeny”.
- Krok 3 — Kliknij „Generuj nowy token”. System poprosi o podanie nazwy tokena (np. „KSeFakt — FV Kowalski Sp. z o.o.”) — ta nazwa ułatwia zarządzanie wieloma tokenami.
- Krok 4 — Wybierz zakres uprawnień tokena:
- Wystawianie faktur — token może wysyłać faktury do KSeF,
- Odbiór faktur — token może pobierać faktury kosztowe z KSeF,
- Zarządzanie — token może zarządzać uprawnieniami (rzadko potrzebne dla programów).
- Krok 5 — System wygeneruje token i wyświetli go jednorazowo na ekranie. Skopiuj go od razu i wklej w program — nie będziesz mógł go ponownie wyświetlić (tylko wygenerować nowy).
- Krok 6 — Wklej token w ustawieniach integracji KSeF w swoim programie do fakturowania. Program zweryfikuje token wysyłając testowe żądanie do API KSeF.
Zakres uprawnień tokena — co może, czego nie może
Token może mieć ograniczony zakres uprawnień — to ważna funkcja bezpieczeństwa. Rekomendowana konfiguracja:
- Token dla programu do wystawiania faktur: uprawnienia „wystawianie” i „odbiór” — wystarczy do normalnej pracy. Nie dawaj tokenu uprawnienia „zarządzanie” — program do faktur nie potrzebuje możliwości zmiany uprawnień w KSeF.
- Token dla programu księgowego (import kosztów): wyłącznie uprawnienie „odbiór” — program pobiera faktury kosztowe, ale nie wystawia nic w Twoim imieniu.
- Token dla integracji biura rachunkowego: uprawnienia dostosowane do zakresu usługi — zazwyczaj „wystawianie” i „odbiór” dla klientów, których obsługuje biuro.
Zasada minimalnych uprawnień: dawaj tokenowi tylko tyle uprawnień, ile rzeczywiście potrzebuje. Jeśli token wycieknie (np. przez podatność bezpieczeństwa w programie), ograniczone uprawnienia minimalizują potencjalne szkody.
Token a sesja API — jak wygląda komunikacja w praktyce
Token KSeF nie jest bezpośrednio używany w każdym żądaniu API — służy do inicjacji sesji. Techniczny przepływ wygląda następująco:
- Program wysyła token do API KSeF w żądaniu inicjacji sesji.
- KSeF weryfikuje token i zwraca tymczasowy identyfikator sesji (session token).
- Wszystkie dalsze operacje (wysyłka faktur, pobieranie faktur) odbywają się w ramach tej sesji — z identyfikatorem sesji, nie z tokenem.
- Sesja wygasa po określonym czasie lub po jej jawnym zamknięciu przez program.
- Przy kolejnej potrzebie komunikacji program inicjuje nową sesję z tym samym tokenem.
Dla użytkownika programu ten przepływ jest niewidoczny — program obsługuje go automatycznie. Ważne: sam token pozostaje stały, a sesje są tymczasowe. Jeśli token wygaśnie lub zostanie odwołany, program nie będzie mógł inicjować nowych sesji i wyśle błąd uwierzytelniania.
Zarządzanie tokenami — odwołanie i odnawianie
| Czynność | Kiedy wykonać | Jak |
|---|---|---|
| Generowanie tokena | Przy pierwszej konfiguracji programu | Aplikacja Podatnika MF → Zarządzanie dostępem → Tokeny |
| Odwołanie tokena | Gdy token wyciekł, gdy zmieniony program, gdy pracownik odszedł | Aplikacja Podatnika MF → Tokeny → Odwołaj |
| Generowanie nowego tokena | Po odwołaniu lub gdy stary token jest nieznany | Jak generowanie — nowy token, nowa nazwa |
| Aktualizacja tokena w programie | Po wygenerowaniu nowego tokena | Ustawienia programu → Integracja KSeF → zaktualizuj token |
Token KSeF nie ma domyślnie daty wygaśnięcia — działa dopóki go nie odwołasz. To różni go od certyfikatu KSeF, który ma określony termin ważności. Odwołanie tokena jest natychmiastowe — od momentu odwołania żaden program korzystający z tego tokena nie może inicjować nowych sesji. Aktywne sesje dokończą się, ale nowych nie będzie można otworzyć.
Bezpieczeństwo tokena — jak nie stracić dostępu do KSeF
Token to wrażliwe dane — jego kradzież daje atakującemu możliwość wystawiania faktur w Twoim imieniu lub pobierania Twoich faktur kosztowych. Zastosuj zasady bezpieczeństwa:
- Nie wklejaj tokena w komentarzu do kodu ani w publicznym repozytorium — programiści często popełniają ten błąd przy integracji własnych systemów z API.
- Przechowuj token w bezpiecznym sejfie haseł (np. menedżer haseł, vault firmowy) — nie w arkuszu Excel ani w e-mailu.
- Jeden token per program — jeśli używasz kilku programów, wygeneruj osobny token dla każdego. Łatwiej odwołać jeden token niż zastanawiać się, który program jest „skompromitowany”.
- Regularny przegląd tokenów — raz na kwartał sprawdź listę aktywnych tokenów w Aplikacji Podatnika MF i odwołaj te, których już nie używasz.
Zapoznaj się też z artykułem o uprawnieniach w KSeF — jeśli token jest przypisany do uprawnień konkretnego pracownika, odwołaj go gdy pracownik odchodzi z firmy.
FAQ — najczęstsze pytania o token KSeF
Czy token KSeF to to samo co token serwera API?
Technicznie token KSeF działa podobnie jak klucz API w innych systemach SaaS. Jest ciągiem znaków potwierdzającym tożsamość aplikacji. Jednak token KSeF ma specyficzne właściwości: jest powiązany z konkretnym NIP i zakresem uprawnień, inicjuje sesje (a nie bezpośrednio transakcje) i jest zarządzany przez Aplikację Podatnika MF.
Czy mogę mieć kilka tokenów dla różnych pracowników?
Tak — każdy token ma swoją nazwę i zakres uprawnień. Możesz wygenerować token dla programu używanego przez pracownicę A i oddzielny token dla programu używanego przez pracownika B. Przy odejściu pracownika odwołujesz tylko jego token.
Co jeśli straciłem token — nie zapisałem go przy generowaniu?
Token wyświetlany jest tylko raz przy generowaniu. Jeśli go nie zapisałeś, nie możesz go odzyskać — musisz wygenerować nowy token, a stary odwołać (lub pozostawić jako nieaktywny, jeśli nie jest przypisany do żadnego programu). Nie ma opcji „pokaż ponownie token”.
Co dalej
Jeśli chcesz, żeby konfiguracja tokena w programie zajęła 2 minuty i od tej chwili faktury szły do KSeF automatycznie — sprawdź cennik KSeFakt albo listę funkcji. Dołącz do listy oczekujących i skonfiguruj integrację z KSeF raz na zawsze.