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.

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

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

POST https://dashboard.bace-iot.com/oauth2/token

Post as form-data

Request Body

Name	Type	Description
client_id*	String	client_id should be request from bace-iot.com
client_secret*	String	client_secret should be requested from bace-iot.com
grant_type*	String	grant_type is always "password"
username*	String	The username of your BACE account. Normally this is an email address.
password*		The user password of your BACE account.

200: OK Authorization succeeded

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

400: Bad Request Request was made with wrong params

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

401: Unauthorized Request was made with invalid credentials.

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

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

Avoid creating new tokens when the old token can still be used securely. Instead use the Refresh Token endpoint introduced below.

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

POST https://dashboard.bace-iot.com/oauth2/token

Post as form-data

Headers

Name	Type	Description
Authorization*	String	Bearer followed by a space and your access token.
Content-Type	String	For example: application/json

Request Body

Name	Type	Description
refresh_token*	String	Refresh token you received with upon your first request
client_secret*	String	client_secret should be requested from bace-iot.com
client_id*	String	client_id should be requested from bace-iot.com
grant_type*	String	refresh_token

200: OK

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

400: Bad Request Request was made with wrong params

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

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

Avoid creating new tokens where possible; refresh your token instead!