Depending on the product, different Grant Types are used as follows:
A. The Authorization Code Flow
- Payment Initiation Live 1.0.0
- Account Information Live 1.0.0
- Confirmation Of Funds Live 1.0.0
B. Client credentials
- Payment Initiation Live 2.0.0
A. The Authorization Code Flow
The Authorization Code grant type is used by web and mobile apps. It differs from most of the other grant types by first requiring the app launch a browser to begin the flow. At a high level, the flow has the following steps:
- The application opens a browser to send the user to the OAuth server;
- The user sees the authorization prompt, log in and approves the app’s request and grant the necessary permissions;
- The user is redirected back to the application with an authorization code in the query string;
- The application exchanges the authorization code for an access token.
A.1. Get the User’s Permission
OAuth is all about enabling users to grant limited access to applications. The application first needs to decide which permissions it is requesting, then send the user to a browser to get their permission. To begin the authorization flow, the application constructs a URL like the following and opens a browser to that URL.
Sandbox: https://identity.dskbank.bg/connect/authorize
Live: https://oauth.dskbank.bg/connect/authorize
response_type=code
client_id=29352915982374239857
redirect_uri=https%3A%2F%2Fexample-app.com%2Fcallback
scope=ais.sandbox state=xcoiv98y2kd22vusuye3kch
Here’s each query parameter explained:
- response_type=code - This tells the authorization server that the application is initiating the authorization code flow;
- client_id - The public identifier for the application, obtained when the developer first registered the application;
- redirect_uri - Tells the authorization server where to send the user back to after they approve the request;
- scope - One string indicating which permissions the application is requesting. The specific OAuth API you’re using will define the scope that it supports;
- state - The application generates a random string and includes it in the request. It should then check that the same value is returned after the user authorizes the app. This is used to prevent CSRF attacks.
When the user visits this URL, the authorization server will present them with a login page asking for user credentials.
When the user successfully logs in, the authorization server will present them with a prompt asking if they would like to authorize this application’s request.
A.2. Redirect Back to the Application
If the user approves the request, the authorization server will redirect the browser back to the redirect_uri specified by the application, adding a code and state to the query string.
For example, the user will be redirected back to a URL such as:
https://example-app.com/redirect
code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3
scope=ais.sandbox
state=xcoiv98y2kd22vusuye3kch
The state value will be the same value that the application initially set in the request. The application is expected to check that the state in the redirect matches the state it originally set. This protects against CSRF and other related attacks.
The code is the authorization code generated by the authorization server. This code is relatively short-lived, typically lasting between 1 to 10 minutes depending on the OAuth service.
A.3. Exchange the Authorization Code for an Access Token
We’re about ready to wrap up the flow. Now that the application has the authorization code, it can use that to get an access token.
Sandbox: https://identity.dskbank.bg/connect/token
Live: https://oauth.dskbank.bg/connect/token
The application makes a POST request to the service’s token endpoint with the following parameters:
Header:
- Content-Type= application/x-www-form-urlencoded
Body:
- grant_type=authorization_code - This tells the token endpoint that the application is using the Authorization Code grant type;
- code - The application includes the authorization code it was given in the redirect;
- redirect_uri - The same redirect URI that was used when registering the application;
- client_id - The application’s client ID;
- client_secret - The application’s client secret. This ensures that the request to get the access token is made only from the application, and not from a potential attacker that may have intercepted the authorization code.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
"token_type":"bearer",
"expires_in":3600
"refresh_token":eyJhbGciOiJSUzI1NiIsImtpZCI6ImZjNWEx
}
The Authorization Code flow is complete! The application now has an access token it can use when making API requests.
A.4. Exchange Refresh Token for an Access Token
We can use the refresh token from the previous request for getting access token, that was generated in the response body to get new access token when the old one is expired.Refresh tokens can be used only one time!
The application makes a POST request to the service’s token endpoint with the following parameters:
Header:
- Content-Type= application/x-www-form-urlencoded
Body:
- grant_type=refresh_token - This tells the token endpoint that the application is using the Refresh Token grant type;
- refresh_token - The application includes the refresh token, that was found in the previous post request for access token;
- client_id - The application’s client ID;
- client_secret - The application’s client secret. This ensures that the request to get the access token is made only from the application, and not from a potential attacker that may have intercepted the authorization code.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
"token_type":"bearer",
"expires_in":3600
"refresh_token":eyJhbGciOiJSUzI1NiIsImtpZCI6ImZjNWEx
}
The Authorization Code flow is complete! The application now has an access token it can use when making API requests.
B. The Client credentials Flow
The Client Credentials grant type is used by clients to obtain an access token outside of the context of a user.
B.1. Get Access Token
Sandbox: https://identity.dskbank.bg/connect/token
Live: https://oauth.dskbank.bg/connect/token
The application makes a POST request to the service’s token endpoint with the following parameters:
Header:
- Content-Type= application/x-www-form-urlencoded
Body:
- grant_type=client_credentials - This tells the token endpoint that the application is using the Client credentials grant type;
- scope - One string indicating which permissions the application is requesting. The specific OAuth API you’re using will define the scope that it supports;
- redirect_uri - The same redirect URI that was used when registering the application;
- client_id - The application’s client ID;
- client_secret - The application’s client secret. This ensures that the request to get the access token is made only from the application, and not from a potential attacker that may have intercepted the authorization code.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
"token_type":"bearer",
"expires_in":3600
"refresh_token":eyJhbGciOiJSUzI1NiIsImtpZCI6ImZjNWEx
}
The Client credentials flow is complete! The application now has an access token it can use when making API requests.
B.2. Exchange Refresh Token for an Access Token
The application makes a POST request to the service’s token endpoint with the following parameters:
Header:
- Content-Type= application/x-www-form-urlencoded
Body:
- grant_type=refresh_token - This tells the token endpoint that the application is using the Refresh Token grant type;
- refresh_token - The application includes the refresh token, that was found in the previous post request for access token;
- client_id - The application’s client ID;
- client_secret - The application’s client secret. This ensures that the request to get the access token is made only from the application, and not from a potential attacker that may have intercepted the authorization code.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
"token_type":"bearer",
"expires_in":3600
"refresh_token":eyJhbGciOiJSUzI1NiIsImtpZCI6ImZjNWEx
}