Certyfikat KSeF vs token: dlaczego postawiliśmy Biurko na certyfikaty

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ę w demonstracyjnym środowisku KSeF, 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:

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 Offline i tak jest potrzebny. Do drugiego kodu QR (KOD II) na fakturze wystawianej w trybie offline potrzebny jest osobny certyfikat KSeF typu Offline. 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 trybu offline, 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 biura, które obsługuje wiele firm, 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ć w demonstracyjnym środowisku 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 domyślnym pierwszym połączeniem firmy z KSeF jest Profil Zaufany (można też podać własny certyfikat KSeF), a certyfikat zamawiamy w MF dopiero po nim. Kolejność ma znaczenie.

Warto też wiedzieć, że uwierzytelnienie certyfikatem wymaga implementacji podpisu XAdES-BES, więc aplikacja łącząca się z API KSeF 2.0 musi umieć go złożyć. To dosłownie sytuacja, w której program księgowy musi coś umieć, żeby certyfikat miał sens.

Czerwiec 2026: MF proponuje 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. Zgodnie z obecnymi przepisami tokeny KSeF wygasają 31 grudnia 2026 r., a decyzji w formie przepisu jeszcze nie ma — bezpieczniej przejść na certyfikat KSeF. 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 Offline nadal jest jedyną drogą do drugiego kodu QR (KOD II). Token nadal nie pozwala wnioskować o certyfikat. Model bezpieczeństwa nadal jest inny.

Gdyby tokeny miały zniknąć, mielibyśmy rację przez przypadek. Jeśli zostaną, 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. 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 potrzebny, jeśli chcesz dodać do faktury offline drugi kod QR (KOD II).

Checklista: co zrobić w swojej firmie

1. Sprawdź, czym dziś logujesz się do KSeF. Jeśli tokenem, ustal kto go wygenerował i jakie uprawnienia w nim zaszyto.

2. Zweryfikuj, czy Twój program księgowy w ogóle obsługuje certyfikat KSeF typu Uwierzytelniający. Jeśli nie, nie połączysz go z KSeF na stałe po wygaśnięciu tokenów.

3. Zamów certyfikat typu Offline, jeśli chcesz mieć realny plan B na awarię KSeF lub brak internetu — z drugim kodem QR (KOD II) na fakturze offline.

4. Ustal, kto w firmie ma uprawnienia w KSeF. Certyfikat ich nie nadaje, tylko z nich korzysta.

5. Wpisz do kalendarza datę ważności certyfikatu. Maksymalnie 2 lata, a odnowienie nie dzieje się samo.

6. Ś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 dodać do faktury offline drugi kod QR. Dla produktu, który ma działać także wtedy, gdy KSeF nie działa, ten drugi jest lepszą opcją.

W Biurko obsługa certyfikatów jest wbudowana od pierwszego dnia: wniosek, przechowywanie, monitoring wygasania, a dla księgowych — bezpłatne miejsce w każdej firmie klienta i przełączanie między firmami jednym kliknięciem. 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 potrzebny do drugiego kodu QR (KOD II) w trybie offline.

Czy tokeny KSeF przestaną działać 31 grudnia 2026? Zgodnie z obecnymi przepisami tokeny KSeF wygasają 31 grudnia 2026 r. Na konsultacjach 9 czerwca 2026 r. MF zaproponowało ich utrzymanie, ale decyzji w formie przepisu jeszcze nie ma — bezpieczniej przejść na certyfikat KSeF. 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 Uwierzytelniający służy do uwierzytelniania w systemie, typ Offline do drugiego kodu QR (KOD II) na fakturach w trybie offline. Generuje się je osobno, jeden certyfikat nie obejmuje obu zastosowań.

Czy certyfikatem KSeF zaloguję się do Aplikacji Podatnika? Tak: certyfikat typu Uwierzytelniający służy do uwierzytelniania zarówno w API KSeF 2.0, jak i w Aplikacji Podatnika, a po stronie aplikacji wymaga podpisu XAdES-BES. Sam wniosek o certyfikat złożysz w Aplikacji Podatnika KSeF 2.0 lub przez API.