API / Techniczne

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

Aplikacja: „Native”

Do czego służy ta instrukcja

Ten artykuł wyjaśnia, jak skonfigurować integrację aplikacji typu Native z REST API xSale (flow autoryzacji: Authorization Code + PKCE + Refresh Token). Ten typ jest przeznaczony dla aplikacji mobilnych i desktopowych, w których użytkownik za pierwszym razem loguje się interaktywnie.

W tym artykule znajdziesz

  • kiedy wybrać integrację typu Native,
  • jak przebiega logowanie i wymiana kodu na tokeny,
  • jak odświeżać tokeny bez ponownego logowania użytkownika,
  • na co zwrócić uwagę w bezpieczeństwie i diagnostyce.

Kiedy stosować

  • gdy integracja działa w aplikacji mobilnej lub desktopowej,
  • gdy użytkownik loguje się przez ekran logowania (redirect do Auth0),
  • gdy aplikacja nie może bezpiecznie przechowywać client_secret,
  • gdy potrzebujesz utrzymać sesję przez refresh_token.

Ważne założenie

Klient otrzymuje gotowe dane konfiguracyjne z panelu xSale i wdraża je w swojej aplikacji.

Dane przekazywane klientowi

  • AUTH0_DOMAIN: login.futuriti.pl
  • AUTH0_CLIENT_ID: identyfikator uzyskany przez panel xSale
  • AUTH0_AUDIENCE: https://api.xsale.ai
  • AUTH0_SCOPE: openid profile email xsale production offline_access
  • REDIRECT_URI: domyślnie http://localhost:8400/callback
  • ORGANIZATION_NAME: nazwa organizacji klienta np. Prezentacja_bfffa785-67b8-4a5f-a4e6-8410db057788

Przykład (Testowy klient)

Szybki przepis (krok po kroku)

  1. Skonfiguruj integracje RestAPI w xSale.
  2. Wykonaj logowanie flow Authorization Code + PKCE (bez client_secret).
  3. Wymień authorization_code na access_token, id_token i refresh_token.
  4. Wywołuj xSale REST API z nagłówkami: Authorization: Bearer {access_token} oraz x-id-token: {id_token}.
  5. Odświeżaj tokeny przez grant_type=refresh_token bez ponownego logowania użytkownika.

Typowe problemy i jak je sprawdzić

  • Brak przekierowania po logowaniu – sprawdź poprawność redirect_uri. Jeśli problem się utrzymuje, zgłoś do xSale/Futuriti (weryfikacja callback po stronie Auth0).
  • invalid_grant – sprawdź code_verifier, jednorazowość kodu i zgodność redirect_uri.
  • 401/403 mimo tokenu – sprawdź, czy wysyłasz oba nagłówki: Authorization oraz x-id-token.
  • Brak refresh tokenu – sprawdź scope offline_access; jeśli nadal brak, zgłoś do xSale/Futuriti (ustawienia tokenów w Auth0).

Szczegóły techniczne

Flow: „Authorization Code + PKCE + Refresh Token”

Rodzaj integracji, w której użytkownik loguje się interaktywnie (mobile/desktop), a aplikacja nie posiada client_secret. Po poprawnym logowaniu aplikacja otrzymuje access_token, id_token i opcjonalnie refresh_token. W xSale REST API wymagane są oba tokeny: access_token oraz id_token (przekazywany jako x-id-token).

Aplikacja generuje PKCE: code_verifier oraz code_challenge (S256), a następnie otwiera endpoint https://login.futuriti.pl/authorize z parametrami: response_type=code, client_id, redirect_uri, scope, audience, code_challenge, code_challenge_method=S256.

Po zalogowaniu Auth0 przekierowuje na REDIRECT_URI z parametrem code. Następnie aplikacja wykonuje wymianę kodu na tokeny przez POST https://login.futuriti.pl/oauth/token.

Przykładowe żądanie wysłane za pomocą CURL:

curl -X POST \
--url 'https://login.futuriti.pl/oauth/token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"grant_type": "authorization_code",
"client_id": "{client_id}",
"code": "{authorization_code}",
"code_verifier": "{code_verifier}",
"redirect_uri": "{redirect_uri}"
}'

Po poprawnym przesłaniu danych serwer autoryzacyjny zwróci tokeny.
Przykładowa odpowiedź z serwera autoryzacyjnego:

JSON

{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
"id_token": "eyJodHRwczovL2Z1dHVyaXRpLnBsL3VzZXJf...",
"refresh_token": "eyJjdHkiOiJSZWZyZXNoVG9rZW4...",
"scope": "openid profile email xsale production offline_access",
"expires_in": 86400,
"token_type": "Bearer"
}

Do autoryzacji/uwierzytelnienia w xSale REST API potrzebne są oba tokeny – access_token i id_token.

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}'

UWAGA! Tokeny powinny być przechowywane i odnawiane dopiero gdy to konieczne. Generowanie nowego tokena przed każdym requestem do xSale REST API może wyczerpać limity i spowodować odrzucenie żądań przez serwer autoryzacyjny.

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