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

NameTypeDescription

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.

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

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

NameTypeDescription

Authorization*

String

Bearer followed by a space and your access token.

Content-Type

String

For example: application/json

Request Body

NameTypeDescription

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

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

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

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

Last updated