# Authentication

## Introduction

The BACE API uses oAuth2 for authorizing API requests. Each request to the BACE API must be signed with valid Bearer access token in the Authorization header. If the Authorization header is missing or invalid, the API will give you a warning.

Requesting and using the token follows the following flow:

1. **Request** access token for *first time* access.
2. **Set** access token in the Authorization header with "Bearer" prefix.
3. **Refresh** access token when expired.

  How to request and refresh your API token is explained below. 

{% hint style="info" %}
Some endpoints require more permissions than the account has access to. If your account lacks the permission to access an endpoint, we will return a HTTP 401 "Unauthorized" response. We show all endpoints that you may have access to in the documentation and it is up to your implementation to handle this response gracefully
{% endhint %}

## First time access: request API token

When you first connect to the API you will need to request a new Bearer Token. For this you will require a BACE account, with client secret and client ID. Contact your Evalan representative if you haven't received these credentials.

In case you have your secure backend server, you can get an API token by making POST request to our authorization endpoint. Requesting a token requires a POST as form-data:

## Request token

<mark style="color:green;">`POST`</mark> `https://dashboard.bace-iot.com/oauth2/token`

Post as form-data

#### Request Body

| Name                                             | Type   | Description                                                           |
| ------------------------------------------------ | ------ | --------------------------------------------------------------------- |
| client\_id<mark style="color:red;">\*</mark>     | String | client\_id should be request from bace-iot.com                        |
| client\_secret<mark style="color:red;">\*</mark> | String | client\_secret should be requested from bace-iot.com                  |
| grant\_type<mark style="color:red;">\*</mark>    | String | grant\_type is always "password"                                      |
| username<mark style="color:red;">\*</mark>       | String | The username of your BACE account. Normally this is an email address. |
| password<mark style="color:red;">\*</mark>       |        | The user password of your BACE account.                               |

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

```javascript
{
    "access_token": "8a0b...", - BACE API Authorization token
    "expires_in": 86400, - token expiration (seconds)
    "token_type": "Bearer", - token type
    "scope": null, - scope is not used for now in the system
    "refresh_token": "1281..." - token, which can be used to refresh BACE API token
}
```

{% endtab %}

{% tab title="400: Bad Request Request was made with wrong params" %}

```javascript
{
    "name": "Bad Request",
    "message": "This client is invalid or must authenticate using a client secret",
    "code": 0,
    "status": 400,
    "type": "filsh\\yii2\\oauth2server\\exceptions\\HttpException"
}
```

{% endtab %}

{% tab title="401: Unauthorized Request was made with invalid credentials." %}

```javascript
{
    "name": "Unauthorized",
    "message": "Invalid username and password combination",
    "code": 0,
    "status": 401,
    "type": "filsh\\yii2\\oauth2server\\exceptions\\HttpException"
}
```

{% endtab %}
{% endtabs %}

In this example, username and passwords are the same credentials you would use to login to the Dashboard; so you would use an email address as the username. The grant\_type must always be “password” and the client\_id and client\_secret are specific to the software client that has been registered.

Now you can set your Authorization header with your newly retrieved BACE Access Token. Use this header for every API request you will do from this point onwards. For example:

```
curl https://dashboard.bace-iot.com/api/v2/physical-device
    -H "Content-Type: application/json"
    -H "Authorization: Bearer 8aob..."
```

{% hint style="info" %}
Avoid creating new tokens when the old token can still be used securely. Instead use the Refresh Token endpoint introduced below.&#x20;
{% endhint %}

## Refresh access token

For security reasons, your token will not be valid indefinitely and needs refreshing. A newly issued token is valid for 24h. Refreshed tokens are valid for 14 days.

This endpoint should be called to refresh your valid token when it nears expiration. Refreshing can be done by making a request with the following POST as form-data:

## Refresh token

<mark style="color:green;">`POST`</mark> `https://dashboard.bace-iot.com/oauth2/token`

Post as form-data

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer followed by a space and your access token. |
| Content-Type                                    | String | For example: application/json                     |

#### Request Body

| Name                                             | Type   | Description                                             |
| ------------------------------------------------ | ------ | ------------------------------------------------------- |
| refresh\_token<mark style="color:red;">\*</mark> | String | Refresh token you received with upon your first request |
| client\_secret<mark style="color:red;">\*</mark> | String | client\_secret should be requested from bace-iot.com    |
| client\_id<mark style="color:red;">\*</mark>     | String | client\_id should be requested from bace-iot.com        |
| grant\_type<mark style="color:red;">\*</mark>    | String | refresh\_token                                          |

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

```javascript
{
    "refreshed": true,
    "expires": "2022-04-04 14:19:49" - new expiration should be 14 days from now 
}
```

{% endtab %}

{% tab title="400: Bad Request Request was made with wrong params" %}

```javascript
{
    "name": "Bad Request",
    "message": "The grant type was not specified in the request",
    "code": 0,
    "status": 400,
    "type": "filsh\\yii2\\oauth2server\\exceptions\\HttpException"
}
```

{% endtab %}
{% endtabs %}

Remember to set your Authorization header properly with a valid BACE API token.

{% hint style="warning" %}
Avoid creating new tokens where possible; refresh your token instead!
{% endhint %}