> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/authentication/authentication-factors/totp-time-based-otp-api/api-reference/otp-initiation.md).

# 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`

{% hint style="info" %}
VIDA supports sandbox and production environment, and the `environment-url` can be found under [Environment](broken://pages/UytI0QVh7VhzaaLwc0cO#urls-for-production-and-sandbox-environment) section
{% endhint %}

#### **Parameters**

| Name                                             | Type   | Description                                                                 |
| ------------------------------------------------ | ------ | --------------------------------------------------------------------------- |
| client\_id<mark style="color:red;">\*</mark>     | String | A unique client id that is shared for each partner.                         |
| client\_secret<mark style="color:red;">\*</mark> | String | A unique key that is generated for each product configured for the partner. |
| type<mark style="color:red;">\*</mark>           | String | <p>Type of the authentication</p><p></p><p>Eg:<br><code>otp</code></p>      |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "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"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

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

{% endtab %}

{% tab title="Python" %}

<pre class="language-python"><code class="lang-python"><strong>import requests
</strong>
url = "https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&#x26;client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&#x26;type=otp"

payload={}
headers = {}

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

print(response.text)
</code></pre>

{% endtab %}

{% tab title="NodeJS" %}

```javascript
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);
});
```

{% endtab %}

{% tab title="Java" %}

```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();
```

{% endtab %}

{% tab title="C#" %}

```csharp
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);
```

{% endtab %}

{% tab title="PHP" %}

```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;
```

{% endtab %}
{% endtabs %}

### Success Response

<pre class="language-json"><code class="lang-json">{
    "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&#x26;client_id=api&#x26;client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&#x26;mode=manual&#x26;execution=CONFIGURE_TOTP",
        "qrUrl": "https://{environment-url}/realms/{partner-id}/protocol/api/init?type=otp&#x26;client_id=api&#x26;client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&#x26;execution=CONFIGURE_TOTP&#x26;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"
<strong>    },
</strong>    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/required-action",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0ZDVlYzUzNy0xNjMxLTQ1ZjEtYmU2Zi0yZWQ5YmQwY2QzYzAiLCJleGVjdXRpb24iOiJDT05GSUdVUkVfVE9UUCIsInRhYl9pZCI6IkpKR0JCV0VDVGxzIiwibmJmIjoxNzAyMzcxNzM1LCJzZXNzaW9uX2NvZGUiOiJXNGY1dGxkV0lSdUJfeFBNSDNjYl9hMWtEaXZCN3I1MWNONUtmTjRxcUEwIiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiSkpHQkJXRUNUbHMiLCJleHAiOjE3MDIzNzIwMzUsImlhdCI6MTcwMjM3MTczNSwiYXV0aF9zZXNzaW9uX2lkIjoiNGQ1ZWM1MzctMTYzMS00NWYxLWJlNmYtMmVkOWJkMGNkM2MwIiwianRpIjoiZTZmNWQzOWQtMDc0Yy00ODlmLWIzMGItMmQ2NzExZmM5YmU5In0.Q6Hx3WduIwKjiC7N8tm2nV7gk-sGt9ihv9Pg1xKd76A",
    "authType": "otp",
    "sessionIdentifier": "JJGBBWECTls"
}
</code></pre>

### Error Response

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

Response Schema

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

For a complete list of error codes and their meanings, refer to the [Error Scenarios](broken://pages/CX6b1aDnL7RxltODUyu8) section.

{% hint style="info" %}
To complete the OTP provisioning process, follow up by using the [OTP Provisioning Completion](broken://pages/7JHCeCVln1o5TpQTcsi9#otp-provisioning-completion) API.
{% endhint %}

## **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<mark style="color:red;">\*</mark> | String | credential id generated during the process of provisioning                  |
| client\_id<mark style="color:red;">\*</mark>     | String | A unique client id that is shared for each partner.                         |
| client\_secret<mark style="color:red;">\*</mark> | String | A unique key that is generated for each product configured for the partner. |
| type<mark style="color:red;">\*</mark>           | String | <p>Type of the authentication</p><p></p><p>Eg:<br><code>otp</code></p>      |

{% hint style="info" %}
The Credential ID can be obtained by decoding the [Signed JWT tokens](broken://pages/Bp47mTxFcxqAdSc7KCxa#otp) received as the access token from the Password Completion API.
{% endhint %}

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "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"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

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

{% endtab %}

{% tab title="Python" %}

```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)
```

{% endtab %}

{% tab title="NodeJS" %}

```javascript
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);
});
```

{% endtab %}

{% tab title="Java" %}

```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();
```

{% endtab %}

{% tab title="C#" %}

```csharp
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);
```

{% endtab %}

{% tab title="PHP" %}

```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;
```

{% endtab %}
{% endtabs %}

### 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.

```json
{
    "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

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

Response Schema

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

For a complete list of error codes and their meanings, refer to the [Error Scenarios](broken://pages/CX6b1aDnL7RxltODUyu8) section.

{% hint style="info" %}
To complete the TOTP Authentication process, follow up by using the [TOTP Authentication Completion](broken://pages/7JHCeCVln1o5TpQTcsi9#otp-authentication-api) API.
{% endhint %}