KSeF API token refresh – odświeżanie tokenów
JWT (accessToken) w KSeF API 2.0 ma ograniczony czas ważności. Aby uniknąć ponownego uwierzytelniania, użyj refreshToken do odświeżenia accessToken.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 /api/v2/auth/token/redeem) otrzymasz accessToken i refreshToken. Zapisz oba tokeny bezpiecznie - accessToken do autoryzacji żądań, refreshToken do odświeżania.
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 /api/v2/auth/token/refresh z refreshToken w ciele żądania. W odpowiedzi otrzymasz nowy accessToken i refreshToken.
4. Zaktualizuj tokeny w aplikacji
Zapisz nowy accessToken i refreshToken w aplikacji. Użyj nowego accessToken do wszystkich kolejnych żądań API. Stary accessToken jest już nieważny.
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 /api/v2/auth/xades-signature lub POST /api/v2/auth/ksef-token), aby uzyskać nową parę tokenów. Nie można odświeżyć wygasłego refreshToken.
Błąd 401 przy odświeżaniu tokena
Sprawdź, czy refreshToken jest poprawny i nie wygasł. Upewnij się, że wysyłasz refreshToken w ciele żądania POST /api/v2/auth/token/refresh, nie w nagłówku Authorization. Zweryfikuj format żądania zgodnie z dokumentacją API.
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). Po każdym odświeżeniu otrzymujesz nowy refreshToken, który zastępuje stary. Stary refreshToken staje się nieważny po użyciu.
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 (kilkanaście minut) 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 jest przekazywany w ciele żądania POST /api/v2/auth/token/refresh.
Endpoint odświeżania tokenów
Endpoint POST /api/v2/auth/token/refresh przyjmuje refreshToken w ciele żądania i zwraca nową parę tokenów: accessToken i refreshToken. Endpoint wymaga autoryzacji - użyj aktualnego accessToken w nagłówku Authorization, jeśli jest jeszcze ważny, lub użyj refreshToken bezpośrednio (w zależności od implementacji API).
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 /api/v2/auth/token/refresh z refreshToken w ciele żądania. W odpowiedzi otrzymasz nowy accessToken i refreshToken. Zaktualizuj tokeny w aplikacji i używaj nowego accessToken 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. Po każdym odświeżeniu otrzymujesz nowy refreshToken, który zastępuje stary. Stary refreshToken staje się nieważny po użyciu.
Co zrobić, gdy refreshToken wygasł?
Gdy refreshToken wygasł, musisz ponownie uwierzytelnić się w systemie używając podpisu XAdES (POST /api/v2/auth/xades-signature) lub tokena KSeF (POST /api/v2/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.