API Authentication

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://qa-sso.vida.id/auth/realms/vida/protocol/openid-connect/token

Headers

Name	Type	Description
Content-Type		Format type of request body

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.

API Responses

Access Token Generated

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

HTTP Status Code: 200

JSON Response

{
    "access_token": "eyJhbGciOiJSb5J4ZTZ…",
    "expires_in": 18000,
    "refresh_expires_in": 1800,
    "token_type": "Bearer",
    "not-before-policy": 1621349762,
    "session_state": "98ffa630-af77-4312-b4b87fc",
    "scope": ""
}

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://qa-sso.vida.id/auth/realms/vida/protocol/openid-connect/token' \
--header 'Authorization: Basic {{auth}}' \
--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'

Python

import requests

url = "https://qa-sso.vida.id/auth/realms/vida/protocol/openid-connect/token"

payload='grant_type=client_credentials&scope=roles&client_id=XXXXXX&client_secret=XXXXXX'
headers = {
  'Authorization': 'Basic {{auth}}',
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

NodeJS

var axios = require('axios');
var qs = require('qs');
var data = qs.stringify({
  'grant_type': 'client_credentials',
  'scope': 'roles',
  'client_id': 'XXXXXX',
  'client_secret': 'XXXXXX' 
});
var config = {
  method: 'post',
  url: 'https://qa-sso.vida.id/auth/realms/vida/protocol/openid-connect/token',
  headers: { 
    'Authorization': 'Basic {{auth}}', 
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type=client_credentials&scope=roles&client_id=XXXXXX&client_secret=XXXXXX");
Request request = new Request.Builder()
  .url("https://qa-sso.vida.id/auth/realms/vida/protocol/openid-connect/token")
  .method("POST", body)
  .addHeader("Authorization", "Basic {{auth}}")
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build();
Response response = client.newCall(request).execute();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://qa-sso.vida.id/auth/realms/vida/protocol/openid-connect/token',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => 'grant_type=client_credentials&scope=roles&client_id=XXXXXX&client_secret=XXXXXX',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic {{auth}}',
    'Content-Type: application/x-www-form-urlencoded'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Access Token Validity

Upon a successful API call, an access token and refresh token will be generated and sent in the response. The received JWT (JSON Web Token) token is required to authenticate all API requests for a limited time. Please refer to the below table for the access token validity period

Environment	Validity
Production	5 minutes
Sandbox	5 hours