Dokumentacja OAuth2
Informacje podstawowe
Przed przystąpieniem do procesu autoryzacji przy użyciu OAuth2 konieczna jest rejestracja aplikacji, prowadząca do wygenerowania danych dostępowych niezbędnych do uwierzytelnienia aplikacji w serwisie Furgonetka.pl. Niezbędne do komunikacji w ramach protokołu OAuth2 jest uzyskanie Client ID, Client Secret oraz w przypadku standardowej autoryzacji użytkownika kodem, ustalenie adresu powrotu na stronę aplikacji. W tym celu należy skorzystać z naszego narzędzia do zarządzania aplikacjami OAuth2.
Tokeny dostępowe są zgodne ze standardem JWT.
Pozyskiwanie tokena
Mając ważny kod, aplikacja zgłasza się po token wykonując żądanie HTTP metodą POST na adres: https://konto.furgonetka.pl/oauth/token, dołączając nagłówek Authorization z odpowiednią zawartością.
Przykład użycia
curl -X "POST" "https://konto.furgonetka.pl/oauth/token" \ -H "Authorization: Basic eyJ...V6w" \ -H "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "grant_type=authorization_code" \ --data-urlencode "code=3ad...5c1" --data-urlencode "redirect_uri=https://example.redirect.uri" \
Opis parametrów żądania | ||
---|---|---|
Authorization | wymagany | Nagłówek HTTP Authorization typu Basic, z zawartością w formie client_id:client_secret (dane otrzymane przy rejestracji aplikacji) w postaci Base64. |
https://konto.furgonetka.pl/oauth/token | wymagany | End-point pozwalający na uzyskanie tokena OAuth2. |
grant_type | wymagany | Rodzaj dostępu potrzebny do uzyskania tokena, w tym przypadku authorization_code. |
code | wymagany | Kod autoryzacyjny uzyskany podczas procesu autoryzacji użytkownika. Przed przesłaniem
należy go zdekodować np. przy pomocy funkcji urldecode($code) . |
redirect_uri | wymagany | Adres powrotu zgodny z tym podanym przy rejestracji aplikacji. |
Po poprawnym wykonaniu żądania, zwrócona zostanie odpowiedź w formacie JSON zawierająca m.in. token dostępowy:
{ "token_type": "Bearer", "expires_in": 2678400, "access_token": "eyJ...aeg", "refresh_token": "def...540", }
Opis parametrów odpowiedzi | |
---|---|
token_type | Typ tokena, w tym przypadku Bearer. |
expires_in | Czas ważności tokena dostępowego w sekundach (30 dni). |
access_token | Token dostępowy. |
refresh_token | Token pozwalający na przedłużenie ważności autoryzacji użytkownika dla aplikacji do 3 miesięcy. |
Przedłużenie ważności tokena
Token dostępowy (access_token) ważny jest 30 dni. Aby nie zmuszać użytkownika do ponownej autoryzacji aplikacji zbyt często, udostępniamy również możliwość odświeżania tokenów. Służy do tego refresh_token, który pozwala na uzyskanie nowego tokena dostępowego dla danego użytkownika bez konieczności ingerencji z jego strony. Taki token jest jednorazowego użytku, a po jego użyciu wygenerowany zostaje nowy token dostępowy (ważny kolejne 30 dni) oraz nowy refresh_token.
Przykład użycia
Przykładowe żądanie o przedłużenie ważności tokena:
curl -X "POST" "https://konto.furgonetka.pl/oauth/token" \ -H "Authorization: Basic eyJ...V6w" \ -H "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "grant_type=refresh_token" \ --data-urlencode "refresh_token=def...540"
Opis parametrów żądania | ||
---|---|---|
Authorization | wymagany | Nagłówek HTTP Authorization typu Basic, z zawartością w formie client_id:client_secret (dane otrzymane przy rejestracji aplikacji) w postaci Base64. |
https://konto.furgonetka.pl/oauth/token | wymagany | End-point pozwalający na uzyskanie tokena OAuth2. |
grant_type | wymagany | Rodzaj dostępu potrzebny do uzyskania tokena, w tym przypadku refresh_token. |
refresh_token | wymagany | Wartość refresh tokena, uzyskanego przy generowaniu poprzedniego tokena dostępowego. |
Po poprawnym wykonaniu żądania, zwrócona zostanie odpowiedź w formacie JSON, zawierająca nowy access_token oraz nowy refresh_token:
{ "token_type": "Bearer", "expires_in": 2678400, "access_token": "eyJ...84c", "refresh_token": "def...861", }
Opis parametrów odpowiedzi | |
---|---|
token_type | Typ tokena, w tym przypadku Bearer. |
expires_in | Czas ważności tokena dostępowego w sekundach (30 dni). |
access_token | Nowy token dostępowy. |
refresh_token | Nowy refresh_token, pozwalający na przedłużenie ważności autoryzacji użytkownika dla aplikacji do 3 miesięcy. |
Pozostałe metody pozyskiwania tokena
Autoryzacja typu "password"
Ta metoda pozyskiwania tokena, zakłada, że aplikacja (klient) poprosi o dane uwierzytelniające użytkownika i prześle je bezpośrednio w żądaniu o token dostępowy. Autoryzacja tego typu jest wykorzystywana, gdy aplikacja potrzebuje wykonywać operacje w imieniu użytkownika.
Przykład użycia
Aby pozyskać token dostępowy należy wysłać żądanie HTTP metodą POST na adres: https://konto.furgonetka.pl/oauth/token, dołączając nagłówek Authorization z odpowiednią zawartością.
curl -X "POST" "https://konto.furgonetka.pl/oauth/token" \ -H "Authorization: Basic eyJ...V6w" \ --data-urlencode "grant_type=password" \ --data-urlencode "scope=api" \ --data-urlencode "username=user@example.uri" \ --data-urlencode "password=p...d"
Opis parametrów żądania | ||
---|---|---|
Authorization | wymagany | Nagłówek HTTP Authorization typu Basic, z zawartością w formie client_id:client_secret (dane otrzymane przy rejestracji aplikacji) w postaci Base64. |
https://konto.furgonetka.pl/oauth/token | wymagany | End-point pozwalający na uzyskanie tokena OAuth2. |
grant_type | wymagany | Rodzaj dostępu potrzebny do uzyskania tokena, w tym przypadku password. |
scope | opcjonalny | Zasięg funkcjonalności do których aplikacja ma mieć dostęp (domyślnie: api). |
username | wymagany | Nazwa użytkownika. |
password | wymagany | Hasło użytkownika. |
Po poprawnym przetworzeniu i weryfikacji żądania, zwrócona zostanie odpowiedź w formacie JSON zawierająca access_token oraz refresh_token.
{ "token_type": "Bearer", "expires_in": 2588400, "access_token": "eyJ...ygA", "refresh_token": "def...ca2", }
Opis parametrów odpowiedzi | |
---|---|
token_type | Typ tokena, w tym przypadku Bearer. |
expires_in | Czas ważności tokena dostępowego w sekundach (30 dni). |
access_token | Token dostępowy. |
refresh_token | Token pozwalający na przedłużenie ważności autoryzacji użytkownika dla aplikacji do 3 miesięcy. |
Autoryzacja typu "client credentials"
Tryb client credentials może być pomocny w przypadku, gdy integrowane są z sobą dwa systemy, np. aplikacja wykonująca żądanie API niewymagające uprawnień użytkownika. Należy pamiętać, iż nie ma możliwości przedłużania ważności tokenów pozyskanych w ten sposób.
Przykład użycia
Aby pozyskać token dostępowy należy wysłać żądanie HTTP metodą POST na adres: https://konto.furgonetka.pl/oauth/token, dołączając nagłówek Authorization z odpowiednią zawartością.
curl -X "POST" "https://konto.furgonetka.pl/oauth/token" \ -H "Authorization: Basic eyJ...V6w" \ --data-urlencode "grant_type=client_credentials" \ --data-urlencode "scope=api"
Opis parametrów żądania | ||
---|---|---|
Authorization | wymagany | Nagłówek HTTP Authorization typu Basic, z zawartością w formie client_id:client_secret (dane otrzymane przy rejestracji aplikacji) w postaci Base64. |
https://konto.furgonetka.pl/oauth/token | wymagany | End-point pozwalający na uzyskanie tokena OAuth2. |
grant_type | wymagany | Rodzaj dostępu potrzebny do uzyskania tokena, w tym przypadku client_credentials. |
scope | opcjonalny | Zasięg funkcjonalności do których aplikacja ma mieć dostęp (domyślnie: api). |
Po poprawnej weryfikacji i przetworzeniu żądania, zwrócona zostanie odpowiedź w formacie JSON, zawierająca access_token ważny 60 minut.
{ "token_type": "Bearer", "expires_in": 3600, "access_token": "eyJ...v6A", }
Opis parametrów odpowiedzi | |
---|---|
token_type | Typ tokena, w tym przypadku Bearer. |
expires_in | Czas ważności tokena dostępowego w sekundach (60 minut). |
access_token | Token dostępowy. |