Authentication

The bearer token is obtained by accessing the VIDA authentication service at the following end-point.

The partner, who is making the API requests, must include a specific type of header, called the "authorisation header", in each request they make. The header should contain a unique token, called a "bearer access token". This token serves as a form of authentication, verifying that the request is coming from a legitimate and authorised source.

Prerequisites

Parameter	Description
client_id	A unique client id that is shared for each partner.
client_secret	A unique key that is auto-generated for each product configured for the partner.

A client ID and secret are provided to each partner and are required in order to use the API. If you do not have a client ID and secret, please refer to the getting API credentials section for information on how to obtain them.

API Description

Authentication API

POST https://{environment-url}/auth/realms/{partner-id}/protoco l/openid-connect/token

VIDA supports sandbox and production environment, and the Authenticationenvironment-url can be found under Environment section

Parameters

Headers

Name	Type	Description
Content-Type*		Format type of request body Value : application/x-www-form-urlencoded

Request Body

Name	Type	Description
grant_type*	String	Valid grant type for this method will be client_credentials
scope	String
client_id*	String	An identifier of the client that is provided by Vida.
client_secret*	String	A secret is known only by the client and Vida authentication service.

Access Token Generated

The input parameters are correct and an access token is generated.

HTTP Status Code: 200

JSON Response

{
    "access_token": "eyJhbGcC00MzQxLWIyNWMtYmQ5MGE4YTNhMTRkIiwiY2x..",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInQ4LTQzNDEtYjI1Yy1iZDkwY..",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "0f3971e4-81d8-4341-b25c-bd90a8a3a14d",
    "scope": "profile"
}

UnAuthorised - Invalid Credentials

The client secret key parameter or its value is either missing or incorrect. The partner must check the client's secret key before sending the request.

HTTP Status Code: 401

JSON Response

{
    "error": "unauthorized_client",
    "error_description": "INVALID_CREDENTIALS: Invalid client credentials"
}

Bad Request - Invalid or Missing Parameter(s)

The client id parameter or its value is either missing or incorrect. The partner must check the client id before sending the request.

HTTP Status Code: 400

JSON Response

{
    "error": "unauthorized_client",
    "error_description": "INVALID_CREDENTIALS: Invalid client credentials"
}

Bad Request - Unsupported Grant Type

The grant type parameter or its value is either missing or incorrect.The partner must check the grant type before sending the request. Valid grant type: client_credentials.

HTTP Status Code: 400

JSON Response

{
    "error": "unsupported_grant_type",
    "error_description": "Unsupported grant_type"
}

Integration Code Snippets

Curl

curl --location --request POST 'https://{{environment-url}}/auth/realms/{{realms}}/protoco
l/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=roles' \
--data-urlencode 'client_id=XXXXXX' \
--data-urlencode 'client_secret=XXXXXX'

Refresh Token

API Description

Authentication API

POST https://{{environment-url}}/auth/realms/{partner-id}/protoco l/openid-connect/token

Headers

Name	Type	Description
Content-Type*		Format type of request body Value : application/x-www-form-urlencoded

Request Body

Name	Type	Description
grant_type*	String	Valid grant type for this API will be refresh_token
scope	String
client_id*	String	An identifier of the client that is provided by Vida.
client_secret*	String	A secret is known only by the client and Vida authentication service.
refresh_token*	String	refresh token acquired from the access token API

Refresh Token Generated

The input parameters are correct and refresh token is generated.

HTTP Status Code: 200

JSON Response

{
    "access_token": "eyJhbGcC00MzQxLWIyNWMtYmQ5MGE4YTNhMTRkIiwiY2x..",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInQ4LTQzNDEtYjI1Yy1iZDkwY..",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "0f3971e4-81d8-4341-b25c-bd90a8a3a14d",
    "scope": "profile"
}

Integration Code Snippets

Curl

curl --location --request POST 'https://{{environment-url}}/auth/realms/{partner-id}/protoco
l/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=roles' \
--data-urlencode 'client_id=XXXXXX' \
--data-urlencode 'client_secret=XXXXXX'
--data-urlencode 'refresh_token=XXXXXX'