| Info |
|---|
Before you get started, make sure you have already created Everifin user account. More details on how to create an user account are here: API Access Prerequisites. Afterwards, you can Connect Bank Account With Everifin UI. |
Authentication is facilitated by OpenID Connect which is a simple identity layer on top of the OAuth 2.0 protocol.
Authorization code grant type
Authorization code grant type is one of possible grant types provided by OAuth protocol. In this case the the client’s service account together with user account are authenticated and if successful the authorization code provided can be exchanged for access token.
| Info |
|---|
Authorization code grant type is supported by default. Other oAuth 2.0 grant types can be configured as well, contact us for more information. |
Step1: Redirect end-user to the Authorization endpoint
request method: GET
The authorization code is a temporary code that the client will exchange for an access token. The code itself is obtained from the authorization server where the user gets a chance to see what information the client (in this case the client is Everifin Application) is requesting, and approve or deny the request.
...
Identity Provider base URL: {{everifin_idp_url}}/auth/realms/{{your_realm_value}}/protocol/openid-connect/auth
Query Parameter | Value | Note |
|---|---|---|
client_id | client ID you received from Everifin | the client_id identifies you as a consumer of this API, not the end user |
redirect_uri | http://localhost | this redirect URI can be used for initial testing. Contact us if you want to use your own custom redirect URIs, we will configure it for you |
response_type | code | |
state | A value that will be passed to the redirect URL as a Query parameter. This value can be used to remember the state of your application at the time of the authentication call | |
code_challenge | Optional, only necessary for PKCE. A challenge for PKCE. The challenge is verified in step2: /token request. | |
code_challenge_method | Optional, only necessary for PKCE. Method used to derive the code challenge for PKCE. We accept the followig value: | |
scope | ais | scope specific to your case. E.g. |
| Info |
|---|
PKCE is not enabled by default. If you want to use PKCE, Contact Us |
Example URL: {{everifin_idp_url}}/auth/realms/{{your_realm_value}}/protocol/openid-connect/auth?client_id={{your_client_id}}&&redirect_uri={{client_redirect_uri}}&response_type=code&state=MY_STATE1&scope={{scope}}
...
This code is then used to request an access and refresh token.
Step2: Obtain Bearer Token from the Token endpoint
request method: POST
| Info |
|---|
We will provide you with your own authentication realm. The value is used in the URL below. |
...
Following parameter should be included in request body, formatted as application/x-www-form-urlencoded. Don't forget to include Content-Type: application/x-www-form-urlencoded in request headers.
Parameter | Value | Note |
|---|---|---|
grant_type | authorization_code | |
code | obtained from redirect uri query parameter from step 1 | |
client_id | same value as client_id query parameter from step 1 | |
client_secret | value provided by Everifin | |
redirect_uri | same value as redirect_uri query parameter from step 1 | |
code_verifier | Optional, only necessary for PKCE. We use it to recompute the |
Response:
JSON object containing access_token and refresh_token.
...
| Code Block | ||
|---|---|---|
| ||
{
"access_token": "9f075bc8059dbc4203860f1857c8548cd705f3760ac0551577565e81de12e7472b62f47f8d6934dc5e05cebcf86ce399e2b5e27a4222a8e51925d25d1c389ba3",
"expires_in": 15003600,
"refresh_expires_in": 36002592000,
"refresh_token": "faf0d3a7b234ae25e4ad1c9e13b39ba8c775cb4355342ab6e71d6fdb1776dc1adcd10cf62cfe9b7d9acb485b5205575d136cf4d0e81027766e8c6e18c9ba11e9",
"token_type": "bearer",
"id_token": "75cb4355342ab6e71d6fdb1776dc1adcd10cf62cfe9b7d9acb485b",
"not-before-policy": 0,
"session_state": "1c01ba2b-76b4-445c-9c56-1fdd4b7c38c7",
"scope": "openid email profile"
} |
...
| Info |
|---|
The Authorization HTTP Header value is used to identify a specific user. If you need to access the API under a context of a different user (e.g. access balances and transaction belonging to someone else), you need to authenticate this different user and use the access_token value specific to this user. |
Refreshing an expired token
Access token expires after some time, this period is specified in the expires_in attribute (in response from step 2). Once the Access_token is expired, you will start getting 401 Unauthorized responses from the API.
...
The following parameters should be included in the request body (application/x-www-form-urlencoded):
Parameter | Value | Note |
|---|---|---|
grant_type | refresh_token | |
client_id | same value as client_id query parameter from step 1 | |
client_secret | Value provided by Everifin | |
refresh_token | value from “refresh_token” field on JSON response from step2 |
| Info |
|---|
Don't forget to include Content-Type: application/x-www-form-urlencoded in request headers. |
Response: JSON object containing access_token and refresh_token.
Logout
When the user decides to end the session, the logout endpoint should be called. This invalidates the refresh_token. The access_token remains valid for the period specified in the /token endpoint response from step 2. Usually, this is a short period of 5 minutes.
...
{{everifin_idp_url}}/auth/realms/{your_realm_value}/protocol/openid-connect/logout
Query Parameter | Value | Note |
|---|---|---|
redirect_uri | Optional, an URL the user should be redirected to after the logout action succeeded |
Following parameters should be included in request body (as application/x-www-form-urlencoded).
Parameter | Value | Note |
|---|---|---|
client_id | same value as client_id query parameter from step 1 | |
refresh_token | value from “refresh_token” field on JSON response from step2 |
| Info |
|---|
Don't forget to include Content-Type: application/x-www-form-urlencoded in request headers. |
...