Portal Deweloperski

Ten przewodnik opisuje autoryzację OAuth i tokeny używane przez Application. Kim są Partner, Application (Client) i User, wyjaśnia artykuł Partner, aplikacja i użytkownik.

Przepływ autoryzacji

Gdy Application ma działać w imieniu Usera, User musi udzielić dostępu przez OAuth:

sequenceDiagram
    actor User
    participant App as Application
    participant OLX as OLX
    App->>User: 1. Pokazuje link autoryzacji OLX
(/oauth/authorize)
    User->>OLX: 2. Otwiera link w przeglądarce, loguje się
i akceptuje Application
    OLX->>User: 3. Przekierowanie przeglądarki z authorization_code
    User->>App: 4. Przeglądarka trafia na redirect_uri
z authorization_code
    App->>OLX: 5. Wymiana authorization_code na tokeny
(grant_type: authorization_code)
    OLX->>App: access_token, refresh_token
    Note over App: Przechowuje tokeny tylko dla tego Usera.
User ich nie widzi.

Operacje

Po autoryzacji User pracuje tylko z Application. Application wywołuje API OLX z zapisanym access_token. User nigdy nie wysyła ani nie odbiera tego tokena:

sequenceDiagram
    actor User
    participant App as Application
    participant API as OLX API
    User->>App: 1. Inicjuje akcję
(bez access_token OLX)
    Note right of User: np. opublikuj tę ofertę na OLX
    App->>API: 2. Żądanie API z access_token
np. POST /adverts
    Note over App,API: access_token użyty tutaj
(tylko Application ↔ API OLX)
Token zostaje w Application
User go nie wysyła ani nie odbiera
    API->>App: 3. Odpowiedź API
sukces / błąd
    App->>User: 4. Pokazuje wynik Userowi
(bez access_token OLX)

Tokeny używane przez Application

W procesie autoryzacji występują następujące elementy:

Kontekst User — token w kontekście konkretnego Usera

Używany, gdy Application działa w imieniu Usera (sprzedawcy / wystawiającego).

• authorization_code — jednorazowy kod, który Application otrzymuje po udzieleniu przez Usera dostępu do konta OLX. Application wymienia ten kod na access_token i refresh_token.
• access_token — token, który Application wysyła z żądaniami API w imieniu tego Usera. Ma ograniczony czas życia (patrz expires_in w odpowiedzi tokenowej). Po wygaśnięciu Application używa refresh_token, aby uzyskać nowy access_token. Z access_token Usera Application może publikować ogłoszenia, odczytywać statusy, odbierać wiadomości i wykonywać inne operacje w zakresie użytkownika. Token Usera John Doe nie może być użyty dla Usera Jane Humbug — magazyn każdego Usera pozostaje oddzielny.
• refresh_token — token używany w kontekście Usera do uzyskania nowego access_token po wygaśnięciu poprzedniego. Żyje dłużej niż access token. Można go używać do wygaśnięcia lub unieważnienia. Flow odświeżania może zwrócić nowy refresh_token — zapisz go i używaj najnowszego. Gdy refresh_token wygaśnie lub stanie się nieważny, User musi ponownie przejść autoryzację, aby uzyskać nowy authorization_code, a potem nowy access_token i refresh_token.

Kontekst Client — token w kontekście Application

Uzyskiwany z grant type client_credentials. Tokeny te nie mają kontekstu Usera. Służą do operacji, które nie wymagają danych Usera — np. kategorie, lokalizacje i inne dane współdzielone między Userami.

• access_token — token, który Application wysyła z żądaniami API w kontekście Application (Client). Ma też ograniczony czas życia; po wygaśnięciu Application żąda nowego z client_id / client_secret i grant_type: client_credentials. W tym flow nie ma refresh_token. Token ten nie może wykonywać akcji w imieniu Usera — tylko dostęp do zasobów współdzielonych.
• client_id / client_secret — dane uwierzytelniające Application z Developer Portal. Razem z grant_type: client_credentials służą do uzyskania tokena w kontekście Client. (client_credentials to nazwa grant type, a nie sam secret.)

Szczegóły żądań, endpointy i scope opisuje sekcja Authentication w dokumentacji API.

Aby zarejestrować się jako Partner i utworzyć Application, postępuj zgodnie z artykułem Dostęp do API.