Nest Bank API

Informacje

< Lista informacji

07. Uwierzytelnianie

Do uwierzytelnienia żądań wykorzystujemy standard oAuth2.  Aby móc uwierzytelnić żądanie należy posiadać ważny token dostępowy (access_token). W celu uzyskania przez Partnera tokena Klient musi przeprowadzić tzw. parowanie aplikacji z kontem w Nest Banku.

Standardowo wg oAuth2 proces ten wygląda następująco:

1.       Klient klika w aplikacji Partnera opcje np. „Połącz z Nest Bankiem”.
2.       Klient jest przekierowywany do banku, gdzie autoryzuje dostęp dla aplikacji Partnera.
3.       Klient loguje się a po zalogowaniu widzi ekran autoryzacji na którym pokazane są dane Partnera i aplikacji, która chce uzyskać dostęp.
4.       Klient autoryzuje dostęp za pomocą kodu SMS lub aplikacji mobilnej banku (w zależności od metody jaką na co dzień używa w banku).
5.       Następuje powrót do aplikacji Partnera i przekazanie kodu autoryzacyjnego (authorizationCode).
6.       Partner korzystając z usługi /grant wymienia authorizatonCode na access token i refresh token.
7.       Od tego momentu aplikacja może korzystać z API podając przy każdym żądaniu access token.
8.       Jeżeli wygaśnie access token musisz go odświeżyć korzystając z refresh tokena. 

 

Przekierowanie na stronę banku.

Aplikacja musi przekierować Klienta do banku w celu wydania tokenów.
Klient w przeglądarce musi być przekierowany na adres:

https://login.nestbank.pl/rest/v1/open/api/request?client_id=$client_id&response_type=$response_type&state=$state&redirect_uri=$redirect_uri&scope=open-api

client_id – unikalny identyfikator aplikacji Partnera;
response_type – zawsze wartość ‘code’;
state - wygenerowany przez Partnera ciąg znaków alfanumerycznych o długości 128 znaków (zabezpieczenie przed atakiem typu cross-site request forgery, niezbędny przy późniejszej wymianie authorization_code na access_token i refresh_token, state powinien być unikatowy i powiązany z klientem w aplikacji Partnera - kolejne parowania aplikacji dla tego samo klienta powinny być wywoływane z tym samym parametrem state);
redirect_uri - adres na który klient ma zostać przekierowany po poprawnej autoryzacji, musi to być jeden z adresów podanych przy rejestracji aplikacji;
scope – zawsze wartość ‘open_api’.

 


Autoryzacja dostępu przez Klienta

Po przekierowaniu do banku Klienta loguje się i zatwierdza dostęp dla aplikacji Partnera. Podczas autoryzacji klient widzi nazwę Partnera i aplikacji, logo i zestaw uprawnień na które udziela zgodę. Dostęp jest autoryzowany po wpisaniu kodu SMS lub za pomocą aplikacji mobilnej banku (w zależności od tego jaką metodę autoryzacji Klient używa w Banku).

 

Przekazanie kodu autoryzacyjnego

Po zautoryzowaniu dostępu Klient jest przekierowany z powrotem do aplikacji na adres:

{{redirect_uri}}?state=$state&code=$authorizationCode

redirect_uri - adres podany przy przekierowaniu Klienta, musi to być jeden z adresów podanych przy rejestracji aplikacji;
state – parametr przesłany przy przekierowaniu Klienta; musisz zweryfikować czy jest taki sam jak przy przekierowaniu – jeśli są różne musisz przerwać proces;
code - kod autoryzacyjny.

Standardowo kod autoryzacyjny jest ważny przez 5 minut. W tym czasie musisz go wymienić na tokeny dostępowe.


Pozyskanie tokenów dostępowych.

Kod autoryzacyjny musisz wymienić na tokeny dostępowe.
W tym celu musisz wykonać POST jako application/x-www-form-urlencoded na:

https://nestapi-sandbox.nestbank.pl/open/api/v1/oauth2/grant

przekazując w ciele wywołania parametry:

code – otrzymany w poprzednim kroku authorization_code;
client_id - unikalny identyfikator aplikacji Partnera;
client_secret – sekret – hasło aplikacji otrzymane przy jej rejestracji;
grant_type - w przypadku wymiany kodu autoryzacyjnego musi to być wartość ‘authorization_code’,
redirect_uri - adres podany przy przekierowaniu Klienta, musi to być jeden z adresów podanych przy rejestracji aplikacji;
scope – zawsze wartość ‘open-api’.

Odpowiedź będzie w formacie application/json. 

Wywołanie:

POST /open/api/v1/oauth2/grant HTTP/1.1
Host: https://nestapi-sandbox.nestbank.pl
Accept: application/json
Content-Type: application/json
scope: open-api
cache-control: no-cache
grant_type=authorization_code&client_secret=&client_secret&client_id=$client_id&redirect_uri=$rediret_uri&code=$authorization_code

Przykładowa odpowiedź:

{

    "token_type": "Bearer",
    
"access_token": "ba0904971ac535f92f31e9810d57d36",
    
"expires_in": 1200,
    
"context_id": 41372,
    
"refresh_token": "d982fb82f45cfa9435809b8d6956137c",
    
"refresh_token_expires_in": 7776000

}

 

token_type – typ tokenów – zawsze ‘Bearer’;
access_token – token dostępowy do autoryzowania wywołań API;
expires_in – czas ważności tokena w sekundach (standardowo 20 minut);
context_id – identyfikator kontekstu Klienta w systemie Banku, używany w wywołaniach usług API,
refresh_token – token używany przy odświeżania tokena dostępowego;
refresh_token_expires_in – czas ważności refresh_token-a (standardowo 90 dni).

Otrzymane tokeny powinny być bezpiecznie zapisane i przechowywane.
Nie powinny być przesyłane do przeglądarki a używane jedynie w komunikacji pomiędzy Twoim serwerem i serwerem Banku.

 

Odświeżanie tokenów dostępowych.

Ze względów bezpieczeństwa tokeny dostępowe mają krótki czas ważności (standardowo 20 minut). Dlatego wymagają odświeżania za pomocą refresh_tokena. W tym celu musisz wykonać POST jako application/x-www-form-urlencoded na https://nestapi-sandbox.nestbank.pl/open/api/v1/oauth2/grant przekazując w ciele wywołania parametry:

refresh_token – token umożliwiający odświeżenie tokena dostępowego;
client_id - unikalny identyfikator aplikacji Partnera;
client_secret – sekret – hasło aplikacji otrzymane przy jej rejestracji;
grant_type - w przypadku odświeżania tokena musi to być wartość ‘refresh_token’,
redirect_uri - adres podany przy przekierowaniu Klienta, musi to być jeden z adresów podanych przy rejestracji aplikacji,
scope – zawsze wartość ‘open-api’.

 

Wywołanie:

POST /open/api/v1/oauth2/grant HTTP/1.1
Host: https://nestapi-sandbox.nestbank.pl
Accept: application/json
Content-Type: application/json
scope: open-api
cache-control: no-cache
grant_type=refresh_token&client_secret=&client_secret&client_id=$client_id&redirect_uri=$rediret_uri&refresh_token=$refresh_token

Róbmy razem bank.

Wypełnij formularz >