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.
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.
{{your_realm_value}} = everifin_app
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. |
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}}
The end user should be redirected to this URL. After the user enters login credentials, she is redirected to the redirect URL specified in the redirect_uri parameter.
The URL the user is redirected to looks like this:
{{client_redirect_uri}}?state=MY_STATE1&session_state=6f21951a-4087-40e8-9955-db3e0c48f77f&code=7f7607a2-eddf-4e1c-ad86-18ed054d23c9.6f21951a-4087-40e8-9955-db3e0c48f77f.9787f652-e5ce-4c60-bbf5-e45c1622b8eb
The authorization code can be obtained from the code URL query parameter. In this case, it would be: 7f7607a2-eddf-4e1c-ad86-18ed054d23c9.6f21951a-4087-40e8-9955-db3e0c48f77f.9787f652-e5ce-4c60-bbf5-e45c1622b8eb
This code is then used to request an access and refresh token.
Step2: Obtain Bearer Token from the Token endpoint
request method: POST
We will provide you with your own authentication realm. The value is used in the URL below.
{{everifin_idp_url}}/auth/realms/{{your_realm_value}}/protocol/openid-connect/token
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 | |
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.
e.g.:
{
"access_token": "9f075bc8059dbc4203860f1857c8548cd705f3760ac0551577565e81de12e7472b62f47f8d6934dc5e05cebcf86ce399e2b5e27a4222a8e51925d25d1c389ba3",
"expires_in": 1500,
"refresh_expires_in": 3600,
"refresh_token": "faf0d3a7b234ae25e4ad1c9e13b39ba8c775cb4355342ab6e71d6fdb1776dc1adcd10cf62cfe9b7d9acb485b5205575d136cf4d0e81027766e8c6e18c9ba11e9",
"token_type": "bearer",
"id_token": "75cb4355342ab6e71d6fdb1776dc1adcd10cf62cfe9b7d9acb485b",
"not-before-policy": 0,
"session_state": "1c01ba2b-76b4-445c-9c56-1fdd4b7c38c7",
"scope": "openid email profile"
}
All API calls should contain the access_token value in the Authorization HTTP Header.
e.g. Authorization: Bearer YOUR_ACCESS_TOKEN_VALUE
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.
You can renew the Access token using the refresh token. A refresh token is valid for a longer period compared to the access token.
request method: POST
{{everifin_idp_url}}/auth/realms/{{your_realm_value}}/protocol/openid-connect/token
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 | |
refresh_token | value from “refresh_token” field on JSON response from step2 |
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.
request method: POST
{{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 |
Don't forget to include Content-Type: application/x-www-form-urlencoded in request headers.
The logout request returns 204 if successful, 400 if not with a json error response
More information about the OpenID connect endpoints is available here: {{everifin_idp_url}}/auth/realms/{{your_realm_value}}/.well-known/openid-configuration
Additional authentication mechanisms
We also support additional authentication mechanisms. These are not available to everyone by default but can be configured upon request.
Identity brokering (If you run your own OpenID connect or SAML2 identity server)
User federation (If you run your own Kerberos, LDAP or Active Directory server)