Before you get started, make sure you have already created an account. More details on how to create an account are here: Create a test account in your realm. Afterwards, you can Connecting Bank Account With Everifin UI.
Methods available
OpenID connect
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol.
Authorization code grant type is supported by default. Other oAuth 2.0 grant types can be configured as well, contact us for more information.
Authorization code grant type
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: https://app.everifin.com/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: |
PKCE is not enabled by default. If you want to use PKCE, Contact Us
Example URL: https://app.everifin.com/auth/realms/{your_realm_value}/protocol/openid-connect/auth/?client_id={your_client_id}&&redirect_uri=http%3A%2F%2Flocalhost%2Fdashboard&response_type=code&state=MY_STATE1
The end user should be redirected to this URL. After the user enters login credentials, she is redirected to the redirect URL (for testing purposes http://localhost).
The URL the user is redirected to looks like this:
http://localhost/?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 token.
Step2: Obtain Bearer Token from the Token endpoint
request method: POST
We will provide you with your own auth realm. The value is used in the URL below.
https://app.everifin.com/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.
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
https://app.everifin.com/auth/realms/{your_realm_value}/protocol/openid-connect/token
The following parameter should be included in the request body 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 | 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 |
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
https://app.everifin.com/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. Don’t forget to include Content-Type: application/x-www-form-urlencoded in request headers.
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 |
returns 204 if successful, 400 if not with a json error response
More information about the OpenID connect endpoints is available here: https://dev.everifin.com/auth/realms/{your_realm_value}/.well-known/openid-configuration
Additional authentication mechanisms
We also support additional authentication mechanisms. These are not available to everyone 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)