> 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/cryptographic-token-pki/integration-methods/api/authentication.md).

# Authentication

The bearer token is obtained by accessing the VIDA authentication service at the following end-point. 

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

{% 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://{environment-url}/auth/realms/{partner-id}/protoco l/openid-connect/token`

{% hint style="info" %}
VIDA supports sandbox and production environment, and the **Authentication**`environment-url` can be found under [Environment](/identity-stack/authentication/authentication-factors/cryptographic-token-pki/integration-methods/api.md#urls-for-production-and-sandbox-environment) section
{% endhint %}

#### **Parameters**

#### Headers

<table><thead><tr><th width="177.36541748046875">Name</th><th width="204.095947265625">Type</th><th>Description</th></tr></thead><tbody><tr><td>Content-Type<mark style="color:red;">*</mark></td><td></td><td>Format type of request body<br>Value : <code>application/x-www-form-urlencoded</code></td></tr></tbody></table>

#### Request Body

| Name                                             | Type   | Description                                                           |
| ------------------------------------------------ | ------ | --------------------------------------------------------------------- |
| grant\_type<mark style="color:red;">\*</mark>    | String | Valid grant type for this method will be `client_credentials`         |
| scope                                            | String |                                                                       |
| client\_id<mark style="color:red;">\*</mark>     | String | An identifier of the client that is provided by Vida.                 |
| client\_secret<mark style="color:red;">\*</mark> | String | A secret is known only by the client and Vida authentication service. |

### Access Token Generated

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

HTTP Status Code: `200`

**JSON Response**

```json
{
    "access_token": "eyJhbGcC00MzQxLWIyNWMtYmQ5MGE4YTNhMTRkIiwiY2x..",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInQ4LTQzNDEtYjI1Yy1iZDkwY..",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "0f3971e4-81d8-4341-b25c-bd90a8a3a14d",
    "scope": "profile"
}
```

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

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

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

```json
{
    "error": "unsupported_grant_type",
    "error_description": "Unsupported grant_type"
}
```

### Integration Code Snippets

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

```groovy
curl --location --request POST 'https://{{environment-url}}/auth/realms/{{realms}}/protoco
l/openid-connect/token' \
--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 %}
{% endtabs %}

## Refresh Token

### API  Description

## Authentication API

<mark style="color:green;">`POST`</mark> `https://{{environment-url}}/auth/realms/{partner-id}/protoco l/openid-connect/token`

#### Headers

<table><thead><tr><th width="171.176513671875">Name</th><th width="194.63690185546875">Type</th><th>Description</th></tr></thead><tbody><tr><td>Content-Type<mark style="color:red;">*</mark></td><td></td><td>Format type of request body<br>Value : <code>application/x-www-form-urlencoded</code></td></tr></tbody></table>

#### Request Body

| Name                                             | Type   | Description                                                           |
| ------------------------------------------------ | ------ | --------------------------------------------------------------------- |
| grant\_type<mark style="color:red;">\*</mark>    | String | Valid grant type for this API will be `refresh_token`                 |
| scope                                            | String |                                                                       |
| client\_id<mark style="color:red;">\*</mark>     | String | An identifier of the client that is provided by Vida.                 |
| client\_secret<mark style="color:red;">\*</mark> | String | A secret is known only by the client and Vida authentication service. |
| refresh\_token<mark style="color:red;">\*</mark> | String | refresh token acquired from the access token API                      |

### Refresh Token Generated

The input parameters are correct and refresh token is generated.

HTTP Status Code: `200`

**JSON Response**

```json
{
    "access_token": "eyJhbGcC00MzQxLWIyNWMtYmQ5MGE4YTNhMTRkIiwiY2x..",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInQ4LTQzNDEtYjI1Yy1iZDkwY..",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "0f3971e4-81d8-4341-b25c-bd90a8a3a14d",
    "scope": "profile"
}
```

### Integration Code Snippets

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

```groovy
curl --location --request POST 'https://{{environment-url}}/auth/realms/{partner-id}/protoco
l/openid-connect/token' \
--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'
--data-urlencode 'refresh_token=XXXXXX'
```

{% endtab %}
{% endtabs %}