Autoryzacja
API umożliwia operowanie tylko na zasobach, do których dany użytkownik ma uprawnienia, dlatego każdy zasób jest dostępny dopiero po autoryzacji. Ma to na celu zabezpieczenie dostępu do zasobów.

OAuth

Autoryzacja w API Oktawave jest oparta o specyfikację OAuth2 oraz OpenID Connect. Proces uwierzytelnienia wymaga potwierdzenia klienta API (klientem API jest aplikacja) oraz użytkownika, w imieniu którego aplikacja będzie wykonywać operacje.
Aby skorzystać z zasobów API Oktawave, każde żądanie musi być zautoryzowane. Do autoryzacji wymagane jest podanie ważnego tokenu. W tym celu należy wykonać dwie operacje:
    Stworzyć (zarejestrować) aplikację klienta,
    Wygenerować token dostępowy na podstawie danych uwierzytelniających aplikację klienta oraz użytkownika.

Rejestracja aplikacji klienta API Oktawave

Wejdź na stronę id.oktawave.com/core/clients i stwórz nowego klienta reprezentującego aplikację korzystającą z API Oktawave.
Podczas tworzenia klienta należy podać:
    identyfikator klienta (ten identyfikator będzie potrzebny do operacji generowania tokena),
    nazwa klienta,
    hasło (hasło będzie potrzebne do operacji generowania tokena),
    czas życia tokena.
Każdy użytkownik może stworzyć dowolną liczbę klientów, jak również wiele skryptów może posługiwać się tym samym ClientId.

Zakres dostępu

Tworząc klienta API użytkownik może określić w jakim zakresie zostanie udzielony mu dostęp do poszczególnych zasobów. Do wyboru są:
    oktawave.api - całkowity dostęp odczytu i modyfikacji wszystkich zasobów,
    oktawave.api.readonly - dostęp tylko do zasobów GET, próba dostępu do zasobu modyfikującego zwróci status 403;
Klient może mieć przypisane oba powyższe zakresy i przesyłać tylko wybrane podczas generowania tokenu.

Token

Następny krok to generowanie tokena. Aby skorzystać z zasobów API, każde żądanie musi być zautoryzowane. Do autoryzacji wymagane jest podanie ważnego tokenu.
Aby go uzyskać, należy wywołać zasób serwera autoryzacyjnego dostępny pod https://id.oktawave.com/core/connect/token
Parametry, które zostały użyte w żądaniu:
    grant_type - typ autoryzacji, w tym momencie dostępny tylko password i refresh_token
    username - nazwa użytkownika Oktawave
    password - hasło użytkownika Oktawave
    scope - zakres dostępu (dostępne są oktawave.api, oktawave.api.readonly i offline_access)
W odpowiedzi serwer prześle access_token o czasie życia zależnym od ustawień nadanych dla klienta.

Żądanie

1
curl -X POST
2
-d "grant_type=password&username=test_login&password=test_pass&scope=oktawave.api offline_access"
3
-u "clientId:clientSecret"
4
'https://id.oktawave.com/core/connect/token'
Copied!

Odpowiedź

1
{
2
"access_token": "09b2c9833d70ec777c406263687853c1",
3
"expires_in": 1000,
4
"token_type": "Bearer"
5
}
Copied!

Odświeżanie tokena

Tokeny powinny mieć krótki czas życia (zazwyczaj jest to kilka minut). Ma to na celu zabezpieczenie zasobów API, nawet w sytuacji gdy token zostanie wykradziony. Żeby uniknąć podawania danych dostępowych za każdym razem gdy token wygaśnie, można skorzystać z mechanizmu odświeżania tokena.
Aby móc skorzystać z mechanizmu odświeżania, należy przede wszystkim dodać podczas pierwszej autoryzacji dodatkowy zakres dostępu (scope) - offline_access.
1
curl -X POST
2
-d "grant_type=password&username=test_login&password=test_pass&scope=oktawave.api offline_access"
3
-u "clientId:clientSecret"
4
'https://id.oktawave.com/core/connect/token'
Copied!
Odpowiedź serwera będzie wtedy wyglądała następująco:
1
{
2
"access_token": "09b2c9833d70ec777c406263687853c1",
3
"expires_in": 1000,
4
"token_type": "Bearer",
5
"refresh_token": "77715c5fd2cb6794437aaa560d63bcf3"
6
}
Copied!
Odświeżenie tokena polega na wysłaniu (w dowolnym momencie) żądania wraz z otrzymanym refresh_token do następującego zasobu (uwaga, zmienia się grant_type):
1
curl -X POST
2
-d "grant_type=refresh_token&refresh_token=77715c5fd2cb6794437aaa560d63bcf3"
3
-u "clientId:clientSecret"
4
'https://id.oktawave.com/core/connect/token'
Copied!
W odpowiedzi otrzymamy nowy access_token i refresh_token.
Każdy refresh_token jest jednorazowy, serwer odrzuci próbę odświeżenia jeśli refresh_token był już użyty.
Last modified 10mo ago