Kiedy w 2025 roku projektowaliśmy warstwę uwierzytelniania w Biurko, mieliśmy do wyboru dwie drogi. Prostą: wkleić token, zapisać go w bazie i mieć integrację z KSeF gotową w tydzień. I trudniejszą: zbudować pełną obsługę certyfikatów KSeF, łącznie z podpisem XAdES-BES, przechowywaniem klucza prywatnego i pilnowaniem dat ważności.
Wybraliśmy trudniejszą. Kosztowało nas to kilka tygodni pracy i jedną porządną wpadkę na środowisku demo, o której napiszę niżej.
Ten tekst nie jest poradą podatkową. Jestem założycielem SaaS-a, nie doradcą podatkowym. To zapis decyzji technicznej i tego, co z niej wynikło.
Token i certyfikat to nie są dwie wersje tego samego
Najczęstsze nieporozumienie: „token i certyfikat to dwa sposoby logowania, wybierz wygodniejszy". Nie do końca.
Ministerstwo Finansów opisuje to jednoznacznie: token zawiera w sobie uprawnienia podatnika, deklarowane w momencie generowania. Certyfikat KSeF jest wyłącznie środkiem uwierzytelnienia, podobnie jak podpis kwalifikowany, i nie przenosi żadnych uprawnień (Certyfikaty KSeF, ksef.podatki.gov.pl).
Praktyczna różnica:
Token Certyfikat KSeF Czym jest ciąg znaków alfanumerycznych para kluczy + certyfikat wydany przez MF Uprawnienia zaszyte w środku brane z KSeF po zalogowaniu Ważność bezterminowa (do 31.12.2026 wg pierwotnego planu) do 2 lat Tryb offline nie obsługuje certyfikat typu 2 jest wymagany Wniosek o certyfikat niemożliwy możliwy Model bezpieczeństwa sekret typu bearer klucz prywatny + podpis XAdES-BES
Ostatni wiersz to sedno. Token działa jak hasło: kto go ma, ten jest Tobą. Certyfikat działa jak podpis: KSeF wysyła challenge, Ty podpisujesz go kluczem prywatnym, a klucz nigdy nie idzie w kanał.
Cztery powody, dla których nie zbudowaliśmy obsługi tokenów
1. Klucz prywatny nie musi opuszczać systemu. Token trzeba przekazać do KSeF przy każdym otwarciu sesji. Certyfikat nie: podpisujesz challenge lokalnie. Jeśli budujesz SaaS, który przechowuje poświadczenia setek firm, to nie jest kosmetyka.
2. Certyfikat typu 2 i tak jest obowiązkowy. Do oznaczenia faktury kodem QR w trybie offline potrzebny jest osobny certyfikat KSeF typu 2. Certyfikaty obu typów generuje się oddzielnie, mają w polu CN dopisek „uwierzytelnianie" albo „offline" (ksef.podatki.gov.pl). Skoro i tak musimy umieć obsłużyć certyfikaty na potrzeby offline24, to budowanie równolegle całej ścieżki tokenowej jest dublowaniem pracy.
3. Tokenem nie wnioskujesz o certyfikat. Uwierzytelnienie tokenem nie pozwala złożyć wniosku o certyfikat KSeF. Jeśli firma zbuduje cały proces na tokenie, to i tak w pewnym momencie musi wrócić do Profilu Zaufanego, podpisu kwalifikowanego albo pieczęci, żeby dostać certyfikat. Ślepa uliczka.
4. Biura rachunkowe. Token ma zaszyty zakres uprawnień do konkretnego podmiotu. Biuro z 80 klientami to 80 tokenów do wygenerowania, przechowania i rotacji. Certyfikat identyfikuje osobę, a uprawnienia do poszczególnych firm KSeF rozstrzyga po zalogowaniu. Dla panelu wielofirmowego to zupełnie inna architektura danych.
Wpadka, którą warto opisać
Pierwsza wersja naszego seedera testowego generowała certyfikat self-signed i próbowała się nim uwierzytelnić na środowisku demo KSeF. System odrzucił połączenie. Certyfikat musi pochodzić z KSeF, wydany po wcześniejszym uwierzytelnieniu Profilem Zaufanym, podpisem kwalifikowanym lub pieczęcią kwalifikowaną. Nie ma drogi na skróty i nie ma „własnego CA".
Straciliśmy dwa dni, zanim to zrozumieliśmy. Dlatego w Biurko pierwszym połączeniem firmy z KSeF jest Profil Zaufany, a certyfikat wnioskujemy dopiero po nim. Kolejność ma znaczenie.
Warto też wiedzieć, że certyfikatem KSeF nie zalogujesz się do bezpłatnych narzędzi MF. Certyfikat typu 1 działa w aplikacjach komercyjnych zintegrowanych z API KSeF 2.0, bo wymaga implementacji podpisu XAdES-BES. To dosłownie sytuacja, w której program księgowy musi coś umieć, żeby certyfikat miał sens.
Czerwiec 2026: MF chce zostawić tokeny. I co teraz?
9 czerwca 2026 r. odbyły się w Ministerstwie Finansów pierwsze konsultacje po częściowym wdrożeniu KSeF. Resort zaproponował, żeby tokeny były dostępne również po 31 grudnia 2026 r., z terminem ważności od 1 do 365 dni i nowym uprawnieniem do automatycznego odnawiania (podsumowanie konsultacji, ksef.podatki.gov.pl).
Uwaga: to propozycja z konsultacji, nie obowiązujące przepisy. Do czasu publikacji zmienionego rozporządzenia obowiązuje pierwotny harmonogram, w którym tokeny kończą się 31 grudnia 2026 r. Zanim podejmiesz decyzję operacyjną, sprawdź aktualne komunikaty na ksef.podatki.gov.pl.
Czy to podważa naszą decyzję? Nie, i to z prostego powodu: żaden z czterech argumentów wyżej nie był argumentem „bo tokeny wygasają". Wygaśnięcie tokenów było dla nas skutkiem ubocznym, nie przesłanką. Certyfikat typu 2 nadal jest jedyną drogą do offline24. Token nadal nie pozwala wnioskować o certyfikat. Model bezpieczeństwa nadal jest inny.
Gdyby tokeny miały zniknąć, mielibyśmy rację przez przypadek. Skoro zostają, mamy rację z właściwego powodu.
Trade-offy, o których dostawcy nie lubią mówić
Uczciwie: certyfikat nie jest darmowym obiadem.
Klucz prywatny trzeba gdzieś trzymać. My szyfrujemy go na poziomie aplikacji i logujemy każdą operację uwierzytelnienia. To dodatkowa odpowiedzialność, której token na siebie nie bierze.
Certyfikat wygasa. Maksymalnie 2 lata. Ktoś musi to pilnować, więc zbudowaliśmy ostrzeżenia z wyprzedzeniem i widoczny status połączenia w panelu.
Certyfikat osoby fizycznej działa w wielu kontekstach. Jeśli księgowa ma uprawnienia do pięciu firm, jej certyfikat uwierzytelnia ją w pięciu kontekstach, nie w jednym. To wygodne i jednocześnie wymaga porządku w uprawnieniach po stronie KSeF. Token daje tu węższy zakres i to jest jego realna zaleta.
Podpis XAdES-BES to praca. Token wkleja się w 30 sekund. Certyfikat wymagał od nas obsługi PEM, P12, walidacji zgodności klucza z certyfikatem i weryfikacji NIP zapisanego w certyfikacie. Klient tego nie widzi i dobrze.
Jeśli szukasz jednego zdania: token jest szybszy na start, certyfikat jest lepszy na dłuższą metę i jest niezbędny, jeśli chcesz fakturować offline.
Checklista: co zrobić w swojej firmie
Sprawdź, czym dziś logujesz się do KSeF. Jeśli tokenem, ustal kto go wygenerował i jakie uprawnienia w nim zaszyto.
Zweryfikuj, czy Twój program księgowy w ogóle obsługuje certyfikat KSeF typu 1. Jeśli nie, tryb offline24 jest dla Ciebie zamknięty.
Wygeneruj certyfikat typu 2, jeśli chcesz mieć realny plan B na awarię KSeF lub brak internetu.
Ustal, kto w firmie ma uprawnienia w KSeF. Certyfikat ich nie nadaje, tylko z nich korzysta.
Wpisz do kalendarza datę ważności certyfikatu. Maksymalnie 2 lata, a odnowienie nie dzieje się samo.
Śledź komunikaty MF w sprawie tokenów. Status na dziś: propozycja, nie przepis.
Podsumowanie
Wybór między certyfikatem a tokenem to nie wybór „nowsze kontra starsze". To wybór między poświadczeniem, które nosi w sobie uprawnienia, a poświadczeniem, które potwierdza tożsamość i pozwala fakturować offline. Dla produktu, który ma działać także wtedy, gdy KSeF nie działa, ten drugi jest jedyną opcją.
W Biurko obsługa certyfikatów jest wbudowana od pierwszego dnia: wniosek, przechowywanie, monitoring wygasania, panel wielofirmowy dla biur rachunkowych. Nie musisz wiedzieć, czym jest XAdES-BES. Załóż darmowe konto na biurko.io i podłącz pierwszą firmę do KSeF.
FAQ
Czym różni się certyfikat KSeF od tokenu? Token zawiera w sobie uprawnienia nadane w momencie jego generowania. Certyfikat KSeF potwierdza wyłącznie tożsamość osoby lub podmiotu, a uprawnienia system pobiera z KSeF po zalogowaniu. Certyfikat ma też termin ważności (do 2 lat) i jest wymagany w trybie offline.
Czy tokeny KSeF przestaną działać 31 grudnia 2026? Taki był pierwotny harmonogram. Po konsultacjach z 9 czerwca 2026 r. MF zaproponowało pozostawienie tokenów jako stałej metody logowania, z ważnością od 1 do 365 dni. To jednak nadal propozycja, a nie obowiązujące przepisy. Sprawdzaj komunikaty na ksef.podatki.gov.pl.
Czy mogę wnioskować o certyfikat KSeF, logując się tokenem? Nie. Uwierzytelnienie tokenem nie pozwala złożyć wniosku o certyfikat. Potrzebujesz Profilu Zaufanego, kwalifikowanego podpisu elektronicznego albo kwalifikowanej pieczęci elektronicznej.
Ile typów certyfikatu KSeF istnieje? Dwa. Typ 1 służy do uwierzytelniania w systemie, typ 2 do oznaczania faktur kodem QR w trybie offline. Generuje się je osobno, jeden certyfikat nie obejmuje obu zastosowań.
Czy certyfikatem KSeF zaloguję się do Aplikacji Podatnika? Certyfikat typu 1 działa w aplikacjach komercyjnych zintegrowanych z API KSeF 2.0, ponieważ wymaga podpisu XAdES-BES. Sam wniosek o certyfikat złożysz w Aplikacji Podatnika KSeF 2.0 lub przez API.