Kiedy można wywołać POST /api/v2/auth/token/redeem?

Po tym, jak GET /api/v2/auth/{referenceNumber} zwróci status.code = 200 (uwierzytelnianie zakończone sukcesem). Gdy status.code = 100 (uwierzytelnianie w toku), trzeba czekać i odpytywać status.

Czy tokeny z /api/v2/auth/token/redeem są jednorazowe?

Tak. Dokumentacja i opis endpointu wskazują, że tokeny można pobrać tylko raz. Dlatego po udanym wywołaniu trzeba je bezpiecznie przechować.

KSeF API: błąd 21301 przy /api/v2/auth/token/redeem (status 100)

Błąd 21301 przy POST /api/v2/auth/token/redeem zwykle oznacza, że próbujesz odebrać tokeny zbyt wcześnie albo ponownie. Kluczowe jest sprawdzenie statusu /api/v2/auth/{referenceNumber}.

Co musisz wiedzieć

W KSeF API 2.0 proces uwierzytelniania jest asynchroniczny. Po wysłaniu żądania uwierzytelniania (np. podpis XAdES lub token KSeF) dostajesz tymczasowy authenticationToken oraz referenceNumber. Ten etap nie daje jeszcze accessToken do wywołań chronionych zasobów.

Zanim wywołasz POST /api/v2/auth/token/redeem, musisz odpytywać GET /api/v2/auth/{referenceNumber} i poczekać aż status operacji pozwoli na pobranie tokenów. W dokumentacji OpenAPI status 100 oznacza uwierzytelnianie w toku, a status 200 oznacza uwierzytelnianie zakończone sukcesem.

Endpoint POST /api/v2/auth/token/redeem zwraca parę tokenów dostępowych i jest jednorazowy: kolejne wywołanie z tym samym uwierzytelnieniem może skończyć się błędem 21301 (np. tokeny zostały już pobrane).

Instrukcja krok po kroku

1. Sprawdź, czy używasz właściwego tokena w Authorization

Do GET /api/v2/auth/{referenceNumber} i POST /api/v2/auth/token/redeem używaj authenticationToken (tymczasowego tokena operacji), przekazywanego w nagłówku Authorization: Bearer. Nie używaj accessToken, bo na tym etapie zwykle go jeszcze nie masz.

2. Odpytuj status GET /api/v2/auth/{referenceNumber}

Wywołuj GET /api/v2/auth/{referenceNumber} aż status.code przestanie być 100. Status 100 oznacza, że uwierzytelnianie nadal trwa i system może weryfikować certyfikat (np. przez OCSP/CRL).

3. Dopiero przy status 200 wywołaj POST /api/v2/auth/token/redeem

Jeśli status.code = 200, wywołaj POST /api/v2/auth/token/redeem z tym samym authenticationToken w Authorization: Bearer. W odpowiedzi otrzymasz accessToken i refreshToken.

4. Nie wywołuj redeem ponownie

Jeżeli raz udało się pobrać tokeny, kolejne próby odebrania tej samej pary mogą skończyć się 21301. Zapisz bezpiecznie accessToken i refreshToken, a po wygaśnięciu accessToken korzystaj z POST /api/v2/auth/token/refresh.

Najczęstsze problemy i rozwiązania

21301: Status uwierzytelniania (100) nie pozwala na pobranie tokenów

To oznacza, że redeem jest wywołany zbyt wcześnie. Odpytuj GET /api/v2/auth/{referenceNumber} aż status.code = 200, a potem ponów POST /api/v2/auth/token/redeem.

21301: Tokeny dla operacji zostały już pobrane

Nie wywołuj /api/v2/auth/token/redeem ponownie dla tej samej operacji. Przechowuj accessToken/refreshToken po pierwszym odebraniu i użyj /api/v2/auth/token/refresh, gdy accessToken wygaśnie.

Długo utrzymuje się status 100

Zaimplementuj polling z rosnącym opóźnieniem (backoff) oraz limitem czasu. Jeżeli status długo nie przechodzi na 200, sprawdź także logikę podpisu/tokena i ewentualne problemy z weryfikacją certyfikatu (OCSP/CRL) po stronie wystawcy.

Co oznacza 21301 w kontekście /api/v2/auth/token/redeem

W specyfikacji OpenAPI dla POST /api/v2/auth/token/redeem kod 21301 jest używany dla scenariuszy braku autoryzacji, m.in. gdy tokeny dla danej operacji zostały już pobrane albo gdy status uwierzytelniania nie pozwala na pobranie tokenów. W praktyce najczęściej oznacza to próbę redeem przy statusie 100 lub duplikat redeem.

Dlaczego status 100 jest normalny (i jak długo może trwać)

Dokumentacja CIRFMF/ksef-docs wskazuje, że na środowiskach przedprodukcyjnym i produkcyjnym system może sprawdzać bieżący status certyfikatu u wystawcy (usługi OCSP/CRL). Do czasu uzyskania odpowiedzi status operacji może pozostawać w stanie uwierzytelnianie w toku i należy go odpytywać do skutku.

Szybka checklista diagnostyczna

Jeśli widzisz 21301: 1) sprawdź, czy odpytałeś GET /api/v2/auth/{referenceNumber} i co zwraca status.code, 2) upewnij się, że w Authorization: Bearer jest authenticationToken, 3) sprawdź, czy nie wywołujesz POST /api/v2/auth/token/redeem wielokrotnie dla tego samego uwierzytelnienia, 4) jeśli status nie przechodzi z 100, wdroż retry z backoff i timeout po stronie klienta.

Oficjalne źródła do weryfikacji

Dokumentacja MF (środowisko testowe): https://api-test.ksef.mf.gov.pl/docs/v2/index.html (patrz GET /api/v2/auth/{referenceNumber} oraz POST /api/v2/auth/token/redeem). Dokumentacja procesu w CIRFMF/ksef-docs: https://github.com/CIRFMF/ksef-docs/tree/main (plik: uwierzytelnianie.md).

FAQ

Czy mogę wywołać /api/v2/auth/token/redeem, gdy status to 100?

Nie. Status 100 oznacza, że uwierzytelnianie nadal trwa. Poczekaj na status 200 w GET /api/v2/auth/{referenceNumber}, a dopiero potem wywołaj redeem.

Skąd mam wziąć referenceNumber do GET /api/v2/auth/{referenceNumber}?

referenceNumber dostajesz w odpowiedzi na rozpoczęcie uwierzytelniania (np. POST /api/v2/auth/xades-signature lub POST /api/v2/auth/ksef-token) razem z authenticationToken.

Czy tokeny z /api/v2/auth/token/redeem można pobrać kilka razy?

Nie. Dokumentacja opisuje, że tokeny można pobrać tylko raz. Kolejne wywołania mogą zakończyć się 21301.

Czy do /api/v2/auth/token/refresh używam refreshToken w Authorization?

Tak. W dokumentacji CIRFMF/ksef-docs refreshToken przekazuje się w Authorization: Bearer i w odpowiedzi dostajesz nowy accessToken.

Powiązane tematy

Przydatne serwisy

Status KSeF

Pierwszy serwis prezentuje informacje o statusie samego KSeF, drugi – komunikaty techniczne Ministerstwa Finansów.