API / Techniczne

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

Aplikacja: „Backend API”

Do czego służy ta instrukcja

Ten artykuł wyjaśnia, jak utworzyć i skonfigurować aplikację typu Backend API dla REST API xSale (flow autoryzacji: Resource Owner Password Credentials). Ten typ jest przeznaczony dla integracji działających bez interakcji z użytkownikiem (np. usługi, skrypty i zadania uruchamiane w tle).

W tym artykule znajdziesz

  • kiedy wybrać aplikację typu Backend API,
  • jak przebiega pozyskanie tokenów w tym modelu,
  • na co zwrócić uwagę w konfiguracji i bezpieczeństwie.

Kiedy stosować

  • gdy integracja działa w tle i nie wykonuje przekierowań do logowania,
  • gdy musisz autoryzować zapytania z backendu,
  • gdy chcesz zautomatyzować cykliczne pobieranie lub wysyłanie danych.

Wymagania

  • dane dostępowe użytkownika i dostęp do konfiguracji aplikacji,
  • bezpieczne przechowywanie sekretów po stronie backendu (nie w przeglądarce).

Szybki przepis (krok po kroku)

  1. Utwórz aplikację typu Backend API.
  2. Skonfiguruj parametry autoryzacji wymagane przez dostawcę uwierzytelniania.
  3. Pobierz tokeny (Access Token / ID Token) zgodnie z opisanym flow.
  4. Użyj tokenów do autoryzacji zapytań do REST API xSale.

Typowe problemy i jak je sprawdzić

  • Błędne dane logowania / brak tokenu — sprawdź poprawność loginu/hasła oraz konfigurację aplikacji (np. zakresy, odbiorcę/audience).
  • Brak dostępu mimo tokenu — upewnij się, że token jest przesyłany prawidłowo w nagłówku autoryzacji i nie wygasł.

Szczegóły techniczne

Flow: „Resource Owner Password Credentials”

Rodzaj aplikacji, w której nie ma interakcji z użytkownikiem (np. skrypt CLI uruchamiany w tle).
Aplikacja uwierzytelnia się przesyłając dane autoryzacyjne wraz z loginem i hasłem użytkownika. Po udanym uwierzytelnianiu otrzymuje Access Token oraz Id Token (https://auth0.com/docs/tokens). Oba tokeny wykorzystywane są do autoryzacji w xSale REST API.

Potrzebna jest lista adresów e-mail użytkowników, którzy mają otrzymać dostęp do xSale REST API.

Żeby autoryzować aplikację i otrzymać tokeny potrzebne do wykonywania akcji w xSale REST API, trzeba wykonać żądanie na adres POST https://login.futuriti.pl/oauth/token wraz z odpowiednimi danymi.

client_id: {client_id},
client_secret: {client_secret},
audience: "https://api.xsale.ai",
username: {your_email},
password: {your_password},
grant_type: "password",
scope: "openid profile email xsale production"

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 '{ \
"client_id": "wWghQGgMuaISx9qEjWi...", \
"client_secret": "vM4a6raBWfKA2VqjZWqu3Er-hRTm...", \
"audience": "https://api.xsale.ai", \
"username": "loremipsum@futuriti.pl", \
"password": "MyPass", \
"grant_type": "password", \
"scope": "openid profile email xsale production" \
}'

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

JSON

{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...", //token autoryzacyjny
"id_token": "eyJodHRwczovL2Z1dHVyaXRpLnBsL3VzZXJf...", //token uwierzytelniający
"scope": "openid profile email xsale production",
"expires_in": 86400, //czas życia tokenów liczony w sekundach
"token_type": "Bearer"
}

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

UWAGA! Tokeny powinny być przetrzymywane jak najdłużej, najlepiej do momentu wygaśnięcia. Generowanie nowego tokena za każdym żądaniem do xSale REST API może spowodować wyczerpanie limitu i być odrzucone przez serwer autoryzacyjny.

Więcej pod adresem:
https://auth0.com/docs/flows/call-your-api-using-resource-owner-password-flow#request-tokens
https://auth0.com/docs/api/authentication#resource-owner-password