OTP - Initiation

TOTP Provisioning

The Time-based One-Time Password (TOTP) Provisioning API is used to create an OTP-based credential for a user. The server will generate a unique TOTP secret which can be used with an TOTP generation tool, like Google Authenticator. This API call will respond with a session ID, bearer token, and a challenge that includes the OTP secret. The user will have to complete this challenge by generating the OTP from their chosen authenticator app and submitting it to the VIDA API.

API Description

Method : GET

URL : https://{environment-url}/realms/{partner-id}/protocol/api/init

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

Parameters

Name	Type	Description
client_id*	String	A unique client id that is shared for each partner.
client_secret*	String	A unique key that is generated for each product configured for the partner.
type*	String	Type of the authentication Eg: otp

200: OK

{
    "entity": {
        "totpSecret": "kWueMqR0Ml70sv5FSB5F",
        "totpSecretEncoded": "NNLX KZKN OFJD ATLM G4YH G5RV IZJU ENKG",
        "totpSecretQrCode": "iVBORw0KGgoAAAANSUhEUgAAAPYAAAD2AQAAAADNaUdlAAACwElEQVR4Xu2XsW7kMAxE1emX3YmdfllFAN973GS96yLViUCAVRawzGFBcIZDp52/nq92j7yfD36PvJ8Pfo+8nz+BR2s939YxYkTrq435CJbgk18crUcb0WeMc67WDVbhRIlEj+MYc66+xuoGC/FoRz8ntzXmOhp5tXiGj0NSpjxlsAo3BWpOQ/Tn6HNmsAhXivN+bvq9w/8TzzNP1EF9j/j8jpbgkaOxhMPhhCb+0GoRDiPDseSxHhJhQJRoGY44HVE84jSvI5RgRsvwnAfQLI/ekMNLGX6mO1ClsvRGgWF7anAq0xZHWNewMohKmdbguAFs0B4SFOjIgi20Bs9m6Ep0CmI45g3fanDnkxyhlOnBkLZrPvbj6pML8hxnWoUL8qnP/TifJe6jYDyhJx67shDvr0NigS6MV3624hqToTPtOcmRrvipbzfOaOZfrgSI0agpbo0qnNZIEbbUcjzTp/pV324cJUwN2gcygRoiaZAl+DJkd1rKYjmoXC7+NuPWF1IjK9TnfcpaEZ569P1Bi+boufqzGZ/ZFOiZdooUO6Ziy3BcyYgQaawqHNOBrcFtTe5ov1CdFXfjS33bcUP6Ii6VcXeUzSrC+XeYFNWR3shFnuaLPvfilKMdk6QyKMsVbYeKcFpyNG3Z57Da6aruz/nZjHOsLDnCpDAKBAJlT/4243jjIEFGmBAHNPVahrMKdCSjI+fTa77U4MtKvocUZfh9SNoBXISjieZwwkxmRndin/60HVeU+EF2Rmy4KthQRXjkegwnIrVxZn29DPekG4bE2ChNIl7ncytuMfph90eldCey1CJ8+oOkcCSzRWojru+D3XhYnvOhTI+0Km+jElchTXM8fSCVee2PCjzHZNoV6cGrFUwRfurNbAd4eWxnW3XNx2481GfojD/W2E3lWoP/cj74PfJ+Pvg98n7+PP4PgcDV9o3EJH0AAAAASUVORK5CYII=",
        "enabled": false,
        "otpCredentials": [],
        "supportedApplications": [
            "totpAppMicrosoftAuthenticatorName",
            "totpAppFreeOTPName",
            "totpAppGoogleName"
        ],
        "manualUrl": "https://{environment-url}/realms/{partner-id}/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&mode=manual&execution=CONFIGURE_TOTP",
        "qrUrl": "https://{environment-url}/realms/{partner-id}/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&execution=CONFIGURE_TOTP&mode=qr",
        "policy": {
            "type": "totp",
            "algorithm": "HmacSHA1",
            "initialCounter": 0,
            "digits": 6,
            "lookAheadWindow": 1,
            "period": 30,
            "codeReusable": false,
            "algorithmKey": "SHA1"
        },
        "username": "57978748-a5ae-4369-8b89-7bb461d964f2"
    },
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/required-action",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0ZDVlYzUzNy0xNjMxLTQ1ZjEtYmU2Zi0yZWQ5YmQwY2QzYzAiLCJleGVjdXRpb24iOiJDT05GSUdVUkVfVE9UUCIsInRhYl9pZCI6IkpKR0JCV0VDVGxzIiwibmJmIjoxNzAyMzcxNzM1LCJzZXNzaW9uX2NvZGUiOiJXNGY1dGxkV0lSdUJfeFBNSDNjYl9hMWtEaXZCN3I1MWNONUtmTjRxcUEwIiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiSkpHQkJXRUNUbHMiLCJleHAiOjE3MDIzNzIwMzUsImlhdCI6MTcwMjM3MTczNSwiYXV0aF9zZXNzaW9uX2lkIjoiNGQ1ZWM1MzctMTYzMS00NWYxLWJlNmYtMmVkOWJkMGNkM2MwIiwianRpIjoiZTZmNWQzOWQtMDc0Yy00ODlmLWIzMGItMmQ2NzExZmM5YmU5In0.Q6Hx3WduIwKjiC7N8tm2nV7gk-sGt9ihv9Pg1xKd76A",
    "authType": "otp",
    "sessionIdentifier": "JJGBBWECTls"
}

Curl

curl --location -g --request GET 'https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=otp'

Python

import requests

url = "https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=otp"

payload={}
headers = {}

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

print(response.text)

NodeJS

var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=otp',
  headers: { }
};

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("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=otp")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();

C#

var client = new RestClient("https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=otp");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=otp',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Success Response

{
    "entity": {
        "totpSecret": "kWueMqR0Ml70sv5FSB5F",
        "totpSecretEncoded": "NNLX KZKN OFJD ATLM G4YH G5RV IZJU ENKG",
        "totpSecretQrCode": "iVBORw0KGgoAAAANSUhEUgAAAPYAAAD2AQAAAADNaUdlAAACwElEQVR4Xu2XsW7kMAxE1emX3YmdfllFAN973GS96yLViUCAVRawzGFBcIZDp52/nq92j7yfD36PvJ8Pfo+8nz+BR2s939YxYkTrq435CJbgk18crUcb0WeMc67WDVbhRIlEj+MYc66+xuoGC/FoRz8ntzXmOhp5tXiGj0NSpjxlsAo3BWpOQ/Tn6HNmsAhXivN+bvq9w/8TzzNP1EF9j/j8jpbgkaOxhMPhhCb+0GoRDiPDseSxHhJhQJRoGY44HVE84jSvI5RgRsvwnAfQLI/ekMNLGX6mO1ClsvRGgWF7anAq0xZHWNewMohKmdbguAFs0B4SFOjIgi20Bs9m6Ep0CmI45g3fanDnkxyhlOnBkLZrPvbj6pML8hxnWoUL8qnP/TifJe6jYDyhJx67shDvr0NigS6MV3624hqToTPtOcmRrvipbzfOaOZfrgSI0agpbo0qnNZIEbbUcjzTp/pV324cJUwN2gcygRoiaZAl+DJkd1rKYjmoXC7+NuPWF1IjK9TnfcpaEZ569P1Bi+boufqzGZ/ZFOiZdooUO6Ziy3BcyYgQaawqHNOBrcFtTe5ov1CdFXfjS33bcUP6Ii6VcXeUzSrC+XeYFNWR3shFnuaLPvfilKMdk6QyKMsVbYeKcFpyNG3Z57Da6aruz/nZjHOsLDnCpDAKBAJlT/4243jjIEFGmBAHNPVahrMKdCSjI+fTa77U4MtKvocUZfh9SNoBXISjieZwwkxmRndin/60HVeU+EF2Rmy4KthQRXjkegwnIrVxZn29DPekG4bE2ChNIl7ncytuMfph90eldCey1CJ8+oOkcCSzRWojru+D3XhYnvOhTI+0Km+jElchTXM8fSCVee2PCjzHZNoV6cGrFUwRfurNbAd4eWxnW3XNx2481GfojD/W2E3lWoP/cj74PfJ+Pvg98n7+PP4PgcDV9o3EJH0AAAAASUVORK5CYII=",
        "enabled": false,
        "otpCredentials": [],
        "supportedApplications": [
            "totpAppMicrosoftAuthenticatorName",
            "totpAppFreeOTPName",
            "totpAppGoogleName"
        ],
        "manualUrl": "https://{environment-url}/realms/{partner-id}/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&mode=manual&execution=CONFIGURE_TOTP",
        "qrUrl": "https://{environment-url}/realms/{partner-id}/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&execution=CONFIGURE_TOTP&mode=qr",
        "policy": {
            "type": "totp",
            "algorithm": "HmacSHA1",
            "initialCounter": 0,
            "digits": 6,
            "lookAheadWindow": 1,
            "period": 30,
            "codeReusable": false,
            "algorithmKey": "SHA1"
        },
        "username": "57978748-a5ae-4369-8b89-7bb461d964f2"
    },
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/required-action",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0ZDVlYzUzNy0xNjMxLTQ1ZjEtYmU2Zi0yZWQ5YmQwY2QzYzAiLCJleGVjdXRpb24iOiJDT05GSUdVUkVfVE9UUCIsInRhYl9pZCI6IkpKR0JCV0VDVGxzIiwibmJmIjoxNzAyMzcxNzM1LCJzZXNzaW9uX2NvZGUiOiJXNGY1dGxkV0lSdUJfeFBNSDNjYl9hMWtEaXZCN3I1MWNONUtmTjRxcUEwIiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiSkpHQkJXRUNUbHMiLCJleHAiOjE3MDIzNzIwMzUsImlhdCI6MTcwMjM3MTczNSwiYXV0aF9zZXNzaW9uX2lkIjoiNGQ1ZWM1MzctMTYzMS00NWYxLWJlNmYtMmVkOWJkMGNkM2MwIiwianRpIjoiZTZmNWQzOWQtMDc0Yy00ODlmLWIzMGItMmQ2NzExZmM5YmU5In0.Q6Hx3WduIwKjiC7N8tm2nV7gk-sGt9ihv9Pg1xKd76A",
    "authType": "otp",
    "sessionIdentifier": "JJGBBWECTls"
}

Error Response

{
    "error": "invalid_request",
    "errorDescription": "Client ID invalid"
}

Response Schema

{
    "error": "{TYPE OF ERROR}",
    "errorDescription": "{REASONING FOR THE ERROR}"
}

For a complete list of error codes and their meanings, refer to the Error Scenarios section.

To complete the OTP provisioning process, follow up by using the OTP Provisioning Completion API.

TOTP Authentication API

The TOTP Authentication API is used when a user wants to authenticate their identity using the OTP method. After initiating a request for authentication, the server will respond with a session ID, bearer token, and a challenge. The user will respond to this challenge by generating and submitting the OTP from their chosen authenticator app. The API will validate this OTP against the secret stored during the provisioning phase.

API Description

Method : GET

URL : https://{environment-url}/realms/{partner-id}/protocol/api/init

Parameters

Name	Type	Description
credential_id*	String	credential id generated during the process of provisioning
client_id*	String	A unique client id that is shared for each partner.
client_secret*	String	A unique key that is generated for each product configured for the partner.
type*	String	Type of the authentication Eg: otp

The Credential ID can be obtained by decoding the Signed JWT tokens received as the access token from the Password Completion API.

200: OK

{
    "entity": {
        "totpSecret": "UsTc6GQwUc12dI4BwnQ1",
        "totpSecretEncoded": "KVZV IYZW I5IX OVLD GEZG ISJU IJ3W 4UJR",
        "totpSecretQrCode": "iVBORw0KGgoAAAANSUhEUgAAAPYAAAD2AQAAAADNaUdlAAACwUlEQVR4Xu2Wsa7rIBBE6fhlOuj4ZRdX4p2zTuLExa0eK10pJHHsHYrRzuzgsn5dP+Ve+Vxf/F75XF/8XvlcfwIfpVQufR2tlT5KPUqfUczBJ99BvVCe3K15lGoxCx88jcqntX5UPlyjmIfPddQ1vQNupfVk/IBZQx6V4q6fpJNwvjSoL0vBlMu7PptxrTjv6+bfO/w/cReqlNbgd9bno5yCj1JHXacpHU5k4oNXk3DqR4l46GyS34FWDGsS/jAFOD/3VUcVukn4gMkkGxRGomD885CF4064HV1TIk0PgrYnB5/K0cfJq9MuhXrjtxtfBqMeZcMgHbtT0vRsEs5IdM9EqDmf9KhjT59ScOjISm/gDueTM2pIMwfHnA6mA9KC2anPaz624zDDHJXe6NSuOO7OwqM7dITyErVHbszCl57QjhHP9sbHfvlzM+5sclEdXUJa8zdNyjSckThbVGxRHM+XP3bjKmE4II+jMs/TIqY1B498KvF2JqZA7/5IwNd4ZjP8vLf2xm8vHsGEHmdMGxGudumzGVcP7UhGuMNHYgK6OfjQEkYkmFmlUE3GSThslrZAGHOB8QSOEyMHN5lmDGm3TxxMXOjUxX8vPuMFpcgPmH9GY0YxB7cz5hNEfU2rIRE9ysL1onJoSWwSbyaENaol4Ut1cCQA3iAomv685nMz7tkEFN0Z8Tnc3p/8duOHrWA2ozsK423YNgc/mU1JNecTm9oo4BwcX5ALbliaU58OE+rFfzdOLhgKTqfyFH0amZWDm0+hTZwOT341DXepSVweKekbSxYuGTjyeoZLhjmBY6SahE+/qlLgR/30xnjN53Z8eBwoERDxhGE8nr3Lw+O1SJFQiYio7+dXAj6cUWxKKp7HFeDKwpdHNNHkqRinMweEu5NwZNGOzqepGCkZPUrCf1lf/F75XF/8Xvlcfx7/B6oL5W5wvIBbAAAAAElFTkSuQmCC",
        "enabled": false,
        "otpCredentials": [],
        "supportedApplications": [
            "totpAppMicrosoftAuthenticatorName",
            "totpAppGoogleName",
            "totpAppFreeOTPName"
        ],
        "manualUrl": "https://{environment-url}/realms/springboot-quickstart/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&mode=manual&execution=CONFIGURE_TOTP",
        "qrUrl": "https://{environment-url}/realms/springboot-quickstart/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&execution=CONFIGURE_TOTP&mode=qr",
        "policy": {
            "type": "totp",
            "algorithm": "HmacSHA1",
            "initialCounter": 0,
            "digits": 6,
            "lookAheadWindow": 1,
            "period": 30,
            "codeReusable": false,
            "algorithmKey": "SHA1"
        },
        "username": "952df4a9-7e56-48e5-b9b6-b3ba5be04ed6"
    },
    "uri": "https://{environment-url}/realms/springboot-quickstart/protocol/api/required-action",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0ZTU1YTZiNi0yYzAxLTQzN2EtOTA1NS01YTE4NTRhNzA5MWIiLCJleGVjdXRpb24iOiJDT05GSUdVUkVfVE9UUCIsInRhYl9pZCI6IkQ1eEs3ZFpTYl9NIiwibmJmIjoxNzAzMDY1ODYyLCJzZXNzaW9uX2NvZGUiOiJnMm5qQjltMUlYQ2xZQzMta3JjajFWUmsyRjNydm1RTXFvNnEyNVdsdktFIiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiRDV4SzdkWlNiX00iLCJleHAiOjE3MDMwNjYxNjIsImlhdCI6MTcwMzA2NTg2MiwiYXV0aF9zZXNzaW9uX2lkIjoiNGU1NWE2YjYtMmMwMS00MzdhLTkwNTUtNWExODU0YTcwOTFiIiwianRpIjoiN2ExZmM3ZDgtMjA3Yy00YzIwLTk4YjUtZTI5MjI4ODQxZGFjIn0.6GmPQFCujbxFrJDVtyNZ2BjIt5gguBL86otkpJSi2Tk",
    "authType": "otp",
    "sessionIdentifier": "D5xK7dZSb_M"
}

Curl

curl --location --request GET 'https://{environment-url}/realms/{partner-id}/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3'

Python

import requests

url = "https://{environment-url}/realms/{partner-id}/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3"

payload={}
headers = {}

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

print(response.text)

NodeJS

var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://{environment-url}/realms/{partner-id}/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3',
  headers: { }
};

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("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://{environment-url}/realms/{partner-id}/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();

C#

var client = new RestClient("https://{environment-url}/realms/{partner-id}/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://{environment-url}/realms/{partner-id}/protocol/api/init?type=otp&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Success Response

The success response contains TOTP secret encoded key and a QR code which can be used to set up the authentication for receiving the TOTP on the supported authenticator apps.

{
    "entity": {
        "selectedCredentialId": "64707473-47ff-4dae-977d-0e16eabc2150",
        "userOtpCredentials": [
            {
                "id": "64707473-47ff-4dae-977d-0e16eabc2150",
                "userLabel": "unnamed"
            }
        ]
    },
    "uri": "https://{environment-url}/realms/springboot-quickstart/protocol/api/authenticate",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJmYmQ1NGFhNy03OGQzLTQxMmItOTk2MS00ZGZmZGIzM2Y2OGEiLCJleGVjdXRpb24iOiJkMGZkNGFjZS02Nzg2LTRlZGYtOWYzMC0wMjgzMDZlMWNhMTAiLCJ0YWJfaWQiOiJzdl9kaUdYV0diRSIsIm5iZiI6MTcwMzU3ODg0NSwic2Vzc2lvbl9jb2RlIjoiS2VmR0hIQk45eFU0ckFTT3VxTEFidWEwLTlPRTM2VE5TRExnbGRORS1QayIsInNlc3Npb25faWRlbnRpZmllciI6InN2X2RpR1hXR2JFIiwiZXhwIjoxNzAzNTc5MTQ1LCJpYXQiOjE3MDM1Nzg4NDUsImF1dGhfc2Vzc2lvbl9pZCI6ImZiZDU0YWE3LTc4ZDMtNDEyYi05OTYxLTRkZmZkYjMzZjY4YSIsImp0aSI6IjQwNGFlOTNjLWQyODgtNGU2OS1hMzNiLTkzZjA4MDYxZTdjYyJ9.8QJzoIN9rVXc-QZWyNUQnpT_FzVy-I8cgh1qMwbuisQ",
    "authType": "otp",
    "sessionIdentifier": "sv_diGXWGbE"
}

Error Response

{
    "error": "invalid_user_credentials",
    "errorDescription": "Unauthorized"
}

Response Schema

{
    "error": "{TYPE OF ERROR}",
    "errorDescription": "{REASONING FOR THE ERROR}"
}

For a complete list of error codes and their meanings, refer to the Error Scenarios section.

To complete the TOTP Authentication process, follow up by using the TOTP Authentication Completion API.