> 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/password-api/api-reference/password-initiation.md).

# Password - Initiation

## Provisioning

The Password-Based Authentication Provisioning API is initiated by the user to establish a password-based credential. In response, the server issues a session ID, bearer token, and a follow-up URL. The user is required to send their chosen password in a subsequent request to the provided follow-up URL to complete the authentication process.

### API  Description

**Method** : GET

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

#### 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><br><code>password</code></p>           |

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

```json
{
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/required-action",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1NGVjNDRjMC04NDk1LTQyMTAtOWNkOS0zOGQ2ZDAwNDhjODciLCJleGVjdXRpb24iOiJ2aWRhLXBhc3N3b3JkLXJlZ2lzdGVyIiwidGFiX2lkIjoiRHloR2ZLRkRxeWsiLCJuYmYiOjE3MDMwNjI0ODAsInNlc3Npb25fY29kZSI6Ikp3Z3ZfbXZLYTlVRDFLSjhMSE1UM1pxVlR3Qy1rb19yMnZSUFRWZnBYejgiLCJzZXNzaW9uX2lkZW50aWZpZXIiOiJEeWhHZktGRHF5ayIsImV4cCI6MTcwMzA2Mjc4MCwiaWF0IjoxNzAzMDYyNDgwLCJhdXRoX3Nlc3Npb25faWQiOiI1NGVjNDRjMC04NDk1LTQyMTAtOWNkOS0zOGQ2ZDAwNDhjODciLCJqdGkiOiJkZThjMWNkOS01NDFiLTRmNzEtOGZhNC1jZWQ0ZmE1YjQyODUifQ.vkJw9mWDU68qyp17BEEmk5Nyxb0perHNljjaOHSZcQw",
    "authType": "password",
    "sessionIdentifier": "DyhGfKFDqyk"
}
```

{% 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=password'
```

{% 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=password"

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=password',
  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=password")
  .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=password");
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=password',
  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

```json
{
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/required-action",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1NGVjNDRjMC04NDk1LTQyMTAtOWNkOS0zOGQ2ZDAwNDhjODciLCJleGVjdXRpb24iOiJ2aWRhLXBhc3N3b3JkLXJlZ2lzdGVyIiwidGFiX2lkIjoiRHloR2ZLRkRxeWsiLCJuYmYiOjE3MDMwNjI0ODAsInNlc3Npb25fY29kZSI6Ikp3Z3ZfbXZLYTlVRDFLSjhMSE1UM1pxVlR3Qy1rb19yMnZSUFRWZnBYejgiLCJzZXNzaW9uX2lkZW50aWZpZXIiOiJEeWhHZktGRHF5ayIsImV4cCI6MTcwMzA2Mjc4MCwiaWF0IjoxNzAzMDYyNDgwLCJhdXRoX3Nlc3Npb25faWQiOiI1NGVjNDRjMC04NDk1LTQyMTAtOWNkOS0zOGQ2ZDAwNDhjODciLCJqdGkiOiJkZThjMWNkOS01NDFiLTRmNzEtOGZhNC1jZWQ0ZmE1YjQyODUifQ.vkJw9mWDU68qyp17BEEmk5Nyxb0perHNljjaOHSZcQw",
    "authType": "password",
    "sessionIdentifier": "DyhGfKFDqyk"
}
```

### 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 Password provisioning process, follow up by using the [Password Provisioning Completion](broken://pages/qT3ZdeLTJKcHrDtw2RzD#provisioning-completion) API.
{% endhint %}

## **Password Authentication API**

The Password Authentication API is employed when a user intends to authenticate their identity using the password method. Upon initiating a request for authentication, the server will reply with a session ID, bearer token, and a challenge. The user must respond to this challenge by submitting the password they have chosen. The API will then validate this password against the credential 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>password</code></p> |

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

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

```json
{
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI5Zjc4Y2I4MS0xMzVmLTQ0ZmYtYjEwYy02MDIzNGFiODI2NTkiLCJleGVjdXRpb24iOiIzNjNmZjlkNi1hODAxLTRiNDEtODRjNS1kZWZiOTcxMmY5NzAiLCJ0YWJfaWQiOiI3U1ZZeGgwZTdYayIsIm5iZiI6MTcwMzA2MzUzOCwic2Vzc2lvbl9jb2RlIjoiNXR0c2p6blRzMTAwQTR5VTcwYnRjSkx1amluS29KYldPTHVwdklsRXVlUSIsInNlc3Npb25faWRlbnRpZmllciI6IjdTVll4aDBlN1hrIiwiZXhwIjoxNzAzMDYzODM4LCJpYXQiOjE3MDMwNjM1MzgsImF1dGhfc2Vzc2lvbl9pZCI6IjlmNzhjYjgxLTEzNWYtNDRmZi1iMTBjLTYwMjM0YWI4MjY1OSIsImp0aSI6IjQ1MjMxZDJhLWYwMzMtNGRhZS1iMzhjLWUyYjU2YjMxMjk5ZiJ9.3xq96LZP34cWddY4pYFC1wafm3c7ujqPZaa8kJgFy2g",
    "authType": "password",
    "sessionIdentifier": "7SVYxh0e7Xk"
}
```

{% endtab %}
{% endtabs %}

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

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://{environment-url}/realms/{partner-id}/protocol/api/init?type=password&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=password&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=password&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=password&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT39");
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=password&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

```json
{
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI5Zjc4Y2I4MS0xMzVmLTQ0ZmYtYjEwYy02MDIzNGFiODI2NTkiLCJleGVjdXRpb24iOiIzNjNmZjlkNi1hODAxLTRiNDEtODRjNS1kZWZiOTcxMmY5NzAiLCJ0YWJfaWQiOiI3U1ZZeGgwZTdYayIsIm5iZiI6MTcwMzA2MzUzOCwic2Vzc2lvbl9jb2RlIjoiNXR0c2p6blRzMTAwQTR5VTcwYnRjSkx1amluS29KYldPTHVwdklsRXVlUSIsInNlc3Npb25faWRlbnRpZmllciI6IjdTVll4aDBlN1hrIiwiZXhwIjoxNzAzMDYzODM4LCJpYXQiOjE3MDMwNjM1MzgsImF1dGhfc2Vzc2lvbl9pZCI6IjlmNzhjYjgxLTEzNWYtNDRmZi1iMTBjLTYwMjM0YWI4MjY1OSIsImp0aSI6IjQ1MjMxZDJhLWYwMzMtNGRhZS1iMzhjLWUyYjU2YjMxMjk5ZiJ9.3xq96LZP34cWddY4pYFC1wafm3c7ujqPZaa8kJgFy2g",
    "authType": "password",
    "sessionIdentifier": "7SVYxh0e7Xk"
}
```

### 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 Password authentication process, follow up by using the [Password Authentication Completion](broken://pages/qT3ZdeLTJKcHrDtw2RzD#password-authentication-api) API.
{% endhint %}