> 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/verify/smart-kyc-fraud-api/api-integration/authentication.md).

# 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

<table><thead><tr><th width="144.76171875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>client_id</td><td>A unique client id that is shared for each partner. </td></tr><tr><td>client_secret</td><td>A unique key that is auto-generated for each product configured for the partner. </td></tr></tbody></table>

{% hint style="info" %}
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](#prerequisites) section for information on how to obtain them.
{% endhint %}

## API  Description

## Authentication API

<mark style="color:green;">`POST`</mark> `https://qa-sso.vida.id/auth/realms/vida/protocol/openid-connect/token`

#### Headers

<table><thead><tr><th width="226">Name</th><th width="226">Type</th><th>Description</th></tr></thead><tbody><tr><td>Content-Type</td><td></td><td>Format type of request body</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="142.734375">Name</th><th width="106.1015625">Type</th><th>Description</th></tr></thead><tbody><tr><td>grant_type<mark style="color:red;">*</mark></td><td>String</td><td>Valid grant type for this method will be client_credentials</td></tr><tr><td>scope</td><td>String</td><td></td></tr><tr><td>client_id<mark style="color:red;">*</mark></td><td>String</td><td>An identifier of the client that is provided by Vida.</td></tr><tr><td>client_secret<mark style="color:red;">*</mark></td><td>String</td><td>A secret is known only by the client and Vida authentication service.</td></tr></tbody></table>

## API Responses

### Access Token Generated

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

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

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

</details>

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

<details>

<summary>JSON Response</summary>

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

</details>

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

<details>

<summary>JSON Response</summary>

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

</details>

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

<details>

<summary>JSON Response</summary>

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

</details>

### Integration Code Snippets

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

```http
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'
```

{% endtab %}

{% tab title="Python" %}

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

{% endtab %}

{% tab title="NodeJS" %}

```javascript

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


```

{% endtab %}

{% tab title="Java" %}

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

{% endtab %}

{% tab title="PHP" %}

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

```

{% endtab %}
{% endtabs %}

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