KSeF błąd 401
Co oznacza błąd 401
Błąd 401 (Unauthorized) to odmowa dostępu spowodowana brakiem uprawnień w KSeF. Oznacza, że użytkownik nie posiada odpowiednich uprawnień do wykonania żądanej operacji w danym kontekście.
Najczęściej pojawia się przy logowaniu (gdy użytkownik nie ma uprawnień w kontekście danego NIP) lub próbie wysyłki faktury (brak uprawnienia InvoiceWrite).
Wynika z braku uprawnień w KSeF - użytkownik może być poprawnie uwierzytelniony (np. przez Profil Zaufany, ePUAP), ale nie posiada wymaganych uprawnień w kontekście, w którym próbuje wykonać operację.
Błąd 401 może również wystąpić, gdy użytkownik loguje się w niewłaściwym kontekście (np. jako osoba fizyczna zamiast w kontekście NIP firmy) lub gdy uprawnienia zostały odebrane lub wygasły.
W przypadku API, błąd 401 może oznaczać nieprawidłowy lub wygasły accessToken, brak odpowiednich uprawnień w tokenie JWT lub próbę wykonania operacji w kontekście, dla którego użytkownik nie ma uprawnień.
Instrukcja krok po kroku
1. Sprawdź, jako kto się logujesz
Upewnij się, że logujesz się w odpowiednim kontekście. Jeśli jesteś właścicielem firmy, loguj się w kontekście NIP firmy, nie jako osoba fizyczna. Jeśli jesteś pracownikiem, upewnij się, że masz nadane odpowiednie uprawnienia przez właściciela lub administratora podmiotu.
2. Sprawdź uprawnienia w kontekście
Sprawdź, czy masz wymagane uprawnienia w kontekście, w którym próbujesz wykonać operację. Dla wysyłki faktur potrzebujesz uprawnienia InvoiceWrite, dla przeglądania faktur - InvoiceRead, dla zarządzania uprawnieniami - CredentialsManage. Użyj endpointu POST /api/v2/permissions/query/personal/grants, aby sprawdzić swoje uprawnienia.
3. Zweryfikuj status uprawnień
Sprawdź, czy Twoje uprawnienia są aktywne. Uprawnienia mogą być nieaktywne, jeśli zostały odebrane lub wygasły. Sprawdź listę nadanych uprawnień używając odpowiednich endpointów wyszukiwania (POST /api/v2/permissions/query/persons/grants) i upewnij się, że uprawnienia mają status Active.
4. Poproś o nadanie uprawnień
Jeśli nie masz wymaganych uprawnień, poproś właściciela podmiotu lub administratora z uprawnieniem CredentialsManage o nadanie odpowiednich uprawnień. W przypadku osób fizycznych prowadzących JDG, możesz nadać sobie uprawnienia po zalogowaniu się jako właściciel.
5. Sprawdź token (dla API)
W przypadku użycia API, sprawdź, czy accessToken jest ważny (nie wygasł). Token JWT ma ograniczony czas ważności określony w polu exp. Jeśli token wygasł, odśwież go za pomocą refreshToken wywołując POST /api/v2/auth/token/refresh. Sprawdź również, czy token zawiera odpowiednie uprawnienia w kontekście, w którym próbujesz wykonać operację.
Najczęstsze problemy i rozwiązania
Błąd 401 pojawia się mimo że jestem właścicielem firmy
Upewnij się, że logujesz się w kontekście NIP firmy, nie jako osoba fizyczna. Przy pierwszym logowaniu wybierz odpowiedni podmiot (NIP) z listy dostępnych kontekstów.
Mam uprawnienia, ale nadal widzę błąd 401
Sprawdź, czy Twoje uprawnienia są aktywne i nie wygasły. Użyj endpointu POST /api/v2/permissions/query/personal/grants, aby zweryfikować status uprawnień. Uprawnienia mogły zostać odebrane lub wygasnąć.
Błąd 401 przy wysyłce faktury przez API
Sprawdź, czy accessToken nie wygasł (pole exp w tokenie JWT). Jeśli wygasł, odśwież token za pomocą POST /api/v2/auth/token/refresh. Upewnij się też, że masz uprawnienie InvoiceWrite.
Przyczyny błędu 401
Błąd 401 może wystąpić z kilku powodów: brak uprawnień w kontekście danego NIP (użytkownik nie ma nadanych uprawnień do działania w imieniu podmiotu), logowanie w niewłaściwym kontekście (np. jako osoba fizyczna zamiast w kontekście NIP firmy), wygasłe lub odebrane uprawnienia (uprawnienia zostały odebrane lub wygasły), nieprawidłowy lub wygasły accessToken (w przypadku API, token JWT wygasł lub nie zawiera odpowiednich uprawnień), próba wykonania operacji wymagającej uprawnień, których użytkownik nie posiada (np. próba wysyłki faktury bez uprawnienia InvoiceWrite).
Różnica między błędem 401 a 403
Błąd 401 (Unauthorized) oznacza brak uprawnień - użytkownik jest poprawnie uwierzytelniony, ale nie posiada wymaganych uprawnień do wykonania operacji. Błąd 403 (Forbidden) oznacza, że dostęp jest zabroniony z innych powodów (np. próba dostępu do zasobu, do którego użytkownik nie ma dostępu, nawet jeśli ma odpowiednie uprawnienia). W praktyce, w KSeF błąd 401 jest znacznie częstszy i zwykle oznacza brak uprawnień w kontekście danego podmiotu.
FAQ
Jak naprawić błąd 401?
Aby naprawić błąd 401, musisz nadać brakujące uprawnienia. Jeśli jesteś właścicielem podmiotu, możesz nadać sobie uprawnienia po zalogowaniu się w kontekście NIP firmy. Jeśli jesteś pracownikiem, poproś właściciela lub administratora o nadanie odpowiednich uprawnień. W przypadku API, sprawdź również, czy accessToken jest ważny i zawiera odpowiednie uprawnienia.
Dlaczego pojawia się błąd 401 po zalogowaniu przez Profil Zaufany?
Błąd 401 po zalogowaniu przez Profil Zaufany oznacza, że chociaż uwierzytelnienie przebiegło pomyślnie, nie masz uprawnień w kontekście, w którym próbujesz wykonać operację. Jeśli jesteś właścicielem firmy, upewnij się, że logujesz się w kontekście NIP firmy, nie jako osoba fizyczna. Jeśli jesteś pracownikiem, poproś o nadanie uprawnień.
Czy błąd 401 może oznaczać problem z certyfikatem?
Błąd 401 zwykle nie oznacza problemu z certyfikatem - problem z certyfikatem zwykle powoduje błąd podczas uwierzytelniania, nie po zalogowaniu. Błąd 401 oznacza, że uwierzytelnienie przebiegło pomyślnie, ale użytkownik nie posiada wymaganych uprawnień. Jednak w przypadku API, nieprawidłowy certyfikat użyty do podpisania AuthTokenRequest może powodować problemy z uwierzytelnianiem.
Co zrobić, jeśli błąd 401 pojawia się tylko przy niektórych operacjach?
Jeśli błąd 401 pojawia się tylko przy niektórych operacjach, oznacza to, że masz uprawnienia do części operacji, ale nie do wszystkich. Sprawdź, jakie uprawnienia posiadasz używając endpointu POST /api/v2/permissions/query/personal/grants. Upewnij się, że masz odpowiednie uprawnienia dla operacji, którą próbujesz wykonać (np. InvoiceWrite dla wysyłki faktur, InvoiceRead dla przeglądania faktur).