KSeF API token refresh – odświeżanie tokenów
Mechanizm odświeżania tokenów w KSeF
Po pomyślnym uwierzytelnieniu w KSeF API 2.0 otrzymujesz parę tokenów: accessToken (JWT o krótkim czasie ważności) oraz refreshToken (ważny do 7 dni).
Gdy accessToken wygaśnie, możesz użyć refreshToken do uzyskania nowego accessToken bez konieczności ponownego uwierzytelniania. RefreshToken może być używany wielokrotnie, dopóki nie wygaśnie.
Mechanizm odświeżania tokenów pozwala na ciągłą pracę z API bez przerywania operacji z powodu wygasłych tokenów, pod warunkiem regularnego odświeżania accessToken przed jego wygaśnięciem.
Instrukcja krok po kroku
1. Uzyskaj parę tokenów
Po pomyślnym uwierzytelnieniu (POST /auth/token/redeem) otrzymasz accessToken i refreshToken. Zapisz oba tokeny bezpiecznie - accessToken do autoryzacji żądań, refreshToken do odświeżania. Tokeny można pobrać tylko raz.
2. Monitoruj czas ważności accessToken
Sprawdź pole exp w tokenie JWT (accessToken), aby określić czas wygaśnięcia. Odśwież token przed wygaśnięciem, najlepiej kilka minut wcześniej, aby uniknąć błędów autoryzacji.
3. Odśwież accessToken
Gdy accessToken wygaśnie lub zbliża się do wygaśnięcia, wywołaj POST /auth/token/refresh, przekazując refreshToken w nagłówku Authorization: Bearer {refreshToken}. W odpowiedzi otrzymasz wyłącznie nowy accessToken - refreshToken nie jest wymieniany i pozostaje ten sam do czasu jego wygaśnięcia.
4. Zaktualizuj token w aplikacji
Zapisz nowy accessToken w aplikacji i używaj go do wszystkich kolejnych żądań API. Stary accessToken jest już nieważny. RefreshToken zachowaj bez zmian - możesz go użyć ponownie przy kolejnym odświeżeniu.
Najczęstsze problemy i rozwiązania
RefreshToken wygasł
RefreshToken ma ważność do 7 dni. Jeśli wygasł, musisz ponownie uwierzytelnić się w systemie (POST /auth/xades-signature lub POST /auth/ksef-token), aby uzyskać nową parę tokenów. Nie można odświeżyć wygasłego refreshToken.
Błąd przy odświeżaniu tokena
Sprawdź, czy refreshToken jest poprawny i nie wygasł. Upewnij się, że przekazujesz refreshToken w nagłówku Authorization: Bearer {refreshToken} przy wywołaniu POST /auth/token/refresh, a nie w ciele żądania. Kod błędu 21301 ("Brak autoryzacji") oznacza, że status operacji uwierzytelniania nie pozwala na odświeżenie tokenu lub token KSeF został unieważniony.
Kiedy odświeżać accessToken?
Odśwież accessToken przed jego wygaśnięciem, najlepiej kilka minut wcześniej. Sprawdź pole exp w tokenie JWT, aby określić dokładny czas wygaśnięcia. Możesz zaimplementować automatyczne odświeżanie w aplikacji, aby uniknąć błędów autoryzacji.
Czy refreshToken może być używany wielokrotnie?
Tak, refreshToken może być używany wielokrotnie do odświeżania accessToken, dopóki nie wygaśnie (maksymalnie 7 dni). W odróżnieniu od accessToken, refreshToken nie jest wymieniany przy każdym odświeżeniu - pozostaje ten sam aż do wygaśnięcia.
Różnica między accessToken a refreshToken
accessToken to token JWT używany do autoryzacji wszystkich operacji API. Ma krótki czas ważności (np. kilkanaście minut, określony w polu exp) i jest przekazywany w nagłówku Authorization: Bearer przy każdym żądaniu. refreshToken służy wyłącznie do odświeżania accessToken, ma dłuższy czas ważności (do 7 dni) i przy wywołaniu POST /auth/token/refresh jest przekazywany w nagłówku Authorization: Bearer {refreshToken}, a nie w ciele żądania.
Endpoint odświeżania tokenów
Endpoint POST /auth/token/refresh przyjmuje refreshToken w nagłówku Authorization i zwraca wyłącznie nowy accessToken - w odróżnieniu od POST /auth/token/redeem (który wydaje pierwszą parę tokenów tylko raz), odświeżenie nie generuje nowego refreshToken. Ten sam refreshToken pozostaje ważny i może być użyty ponownie przy kolejnych odświeżeniach, aż do jego wygaśnięcia.
Strategie odświeżania tokenów
Zaimplementuj automatyczne odświeżanie tokenów w aplikacji: monitoruj czas wygaśnięcia accessToken (pole exp w JWT), odśwież token przed wygaśnięciem (np. 5 minut wcześniej), obsługuj błędy odświeżania (np. wygasły refreshToken wymaga ponownego uwierzytelnienia), oraz zaktualizuj tokeny we wszystkich aktywnych sesjach/żądaniach.
Bezpieczeństwo tokenów
Tokeny są danymi wrażliwymi - przechowuj je bezpiecznie, nie loguj w plaintext, używaj szyfrowania w spoczynku. W przypadku kompromitacji tokena natychmiast odwołaj go (jeśli możliwe) lub poczekaj na wygaśnięcie. RefreshToken ma dłuższy czas ważności, więc jego kompromitacja jest bardziej niebezpieczna niż accessToken.
FAQ
Jak odświeżyć accessToken w KSeF API?
Wywołaj endpoint POST /auth/token/refresh, przekazując refreshToken w nagłówku Authorization: Bearer {refreshToken}. W odpowiedzi otrzymasz wyłącznie nowy accessToken. Zaktualizuj token w aplikacji i używaj go do wszystkich kolejnych żądań API.
Jak długo ważny jest refreshToken?
RefreshToken jest ważny do 7 dni od momentu wygenerowania. Po wygaśnięciu refreshToken musisz ponownie uwierzytelnić się w systemie, aby uzyskać nową parę tokenów.
Czy mogę użyć refreshToken wielokrotnie?
Tak, refreshToken może być używany wielokrotnie do odświeżania accessToken, dopóki nie wygaśnie. W odróżnieniu od accessToken, refreshToken nie jest wymieniany przy odświeżaniu - ten sam token pozostaje ważny aż do upływu maksymalnie 7 dni.
Co zrobić, gdy refreshToken wygasł?
Gdy refreshToken wygasł, musisz ponownie uwierzytelnić się w systemie używając podpisu XAdES (POST /auth/xades-signature) lub tokena KSeF (POST /auth/ksef-token), aby uzyskać nową parę tokenów (accessToken i refreshToken).
Kiedy powinienem odświeżać accessToken?
Odśwież accessToken przed jego wygaśnięciem, najlepiej kilka minut wcześniej. Sprawdź pole exp w tokenie JWT, aby określić dokładny czas wygaśnięcia. Zaimplementuj automatyczne odświeżanie w aplikacji, aby uniknąć błędów autoryzacji.
Powiązane tematy
Przydatne serwisy
Status i komunikaty
API i narzędzia
Pierwsza grupa – status systemu KSeF i komunikaty techniczne Ministerstwa Finansów, druga – narzędzia do integracji z KSeF i walidacji faktur.