API / Techniczne

⌘K
  2. Strona główna
  4. Dokumentacja
  6. API / Techniczne
  8. Autoryzacja, limity
  10. Aplikacja: „Regular Web Application”

Aplikacja: „Regular Web Application”

Do czego służy ta instrukcja

Ten artykuł wyjaśnia, jak skonfigurować integrację typu Regular Web Application z REST API xSale (flow autoryzacji: Authorization Code + PKCE + Refresh Token). Ten typ jest przeznaczony dla aplikacji webowych z backendem.

W tym artykule znajdziesz

  • kiedy wybrać aplikację typu Regular Web Application,
  • jak przebiega logowanie użytkownika i wymiana kodu na tokeny,
  • jak odświeżać tokeny po stronie backendu bez ponownego logowania usera,
  • jak poprawnie autoryzować wywołania xSale API.

Kiedy stosować

  • gdy masz klasyczną aplikację webową z backendem,
  • gdy user loguje się przez przeglądarkę,
  • gdy backend wykonuje wywołania do xSale API w tle,
  • gdy chcesz działać bez client_secret i używać PKCE.

Ważne założenie

Klient nie konfiguruje Auth0 samodzielnie. Otrzymuje gotowe dane konfiguracyjne od xSale/Futuriti (poprzez panel xSale) i wdraża je w backendzie.

Dane przekazywane klientowi

  • AUTH0_DOMAIN: login.futuriti.pl
  • AUTH0_CLIENT_ID: identyfikator aplikacji RWA, do uzyskania w panelu xSale
  • AUTH0_AUDIENCE: https://api.xsale.ai
  • AUTH0_SCOPE: openid profile email xsale production offline_access
  • REDIRECT_URI: uzgodniony callback backendu
  • ORGANIZATION_NAME: nazwa organizacji klienta

Przykład (Testowy klient)

Szybki przepis (krok po kroku)

  1. Skonfiguruj backend danymi przekazanymi przez xSale/Futuriti.
  2. Wygeneruj PKCE (code_verifier, code_challenge) i zrób redirect usera na endpoint /authorize.
  3. Po powrocie na callback odbierz authorization_code.
  4. Wymień kod na tokeny przez POST /oauth/token (authorization_code grant) z code_verifier.
  5. Wywołuj xSale API z nagłówkami: Authorization i x-id-token.
  6. Odnawiaj tokeny przez grant_type=refresh_token bez udziału usera.

Typowe problemy i jak je sprawdzić

  • callback mismatch – sprawdź zgodność REDIRECT_URI z konfiguracją Auth0.
  • invalid_grant – sprawdź poprawność kodu, callbacku i code_verifier.
  • 401/403 mimo tokenu – sprawdź nagłówek x-id-token, scope oraz ważność tokenu.
  • Brak refresh tokenu – sprawdź offline_access i konfigurację refresh tokenów.

Szczegóły techniczne

Flow: „Authorization Code + PKCE + Refresh Token”

Backend robi redirect usera na https://login.futuriti.pl/authorize z parametrami PKCE. Po zalogowaniu user wraca na callback z parametrem code. Backend wymienia code na tokeny przez POST https://login.futuriti.pl/oauth/token i wykonuje wywołania do xSale API.

Przykładowe wywołanie API:

curl -X GET \
--url 'https://api.xsale.ai/me' \
--header 'Authorization: Bearer {access_token}' \
--header 'x-id-token: {id_token}'

Jak korzystać z refresh tokena

Refresh token służy do uzyskania nowego access_token, gdy poprzedni wygasa.

Przykładowe żądanie refresh:

curl -X POST \
--url 'https://login.futuriti.pl/oauth/token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"grant_type": "refresh_token",
"client_id": "{client_id}",
"refresh_token": "{refresh_token}",
"scope": "openid profile email xsale production offline_access",
"audience": "https://api.xsale.ai"
}'

Po refreshu:

  • zapisz nowy access_token,
  • jeśli odpowiedź zawiera nowy refresh_token, nadpisz stary,
  • jeśli odpowiedź zawiera nowy id_token, zaktualizuj go,
  • jeśli brak nowego id_token, użyj ostatniego ważnego do nagłówka x-id-token.

UWAGA! Nie generuj nowego tokenu przed każdym requestem. Trzymaj tokeny w bezpiecznym storage backendu i odświeżaj dopiero gdy to konieczne.

Więcej pod adresem:
https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce
https://auth0.com/docs/secure/tokens/refresh-tokens/use-refresh-tokens