An intro to Config API

  • Updated

An intro to Config API

Config API exposes the functionality of the web-based platform, Bluedot Canvas, as RESTful web services.

Given the Config APIs are based entirely on JSON, a broad range of clients and integrations can be built to utilise these services.

Data added through the Config APIs can be reviewed and edited via the Bluedot Canvas web user-interface and vice versa.

How to authenticate with Config API

1. Make a POST request to the /sessions with your credentials

const sessionsEndPoint= "https://config.bluedot.io/prod1/sessions/";
const credentials = {
    "email": "user@email.com",
    "password": "password123"
};
fetch(sessionsEndPoint, credentials).then(reponse => {
     /*
     The response will return an object with the following structure:
     {
         "status": "success",
         "idToken": "string",
         "accessToken": "string",
         "refreshToken": "string"
     }
     */
     // Attach the returned "accessToken" in the header of any subsequent call to the API
     const { accessToken } = response
})

2. Attach the returned accessToken as Authorization: Bearer <token> in the HTTP header of any subsequent call to the API

Expiry time of the Tokens
  • accessToken: An Access Token is a credential that can be used by an application to access the Configuration API. It is active for 1 hour.
  • refreshToken: The Refresh Token is a special token that can be used to obtain a renewed accessToken. It is active for 60 days.
Best Practises on using the Session API
  1. Have a fail/retry strategy for using the access token – if it expires, catch the failure, reauthenticate to get a new access token and try again.
  2. The refresh token can be used, but for an m2m integration, it’s less important (the email/password can be used instead). The refresh token is typically used by less secure clients such as browsers.

Config API model objects

You will largely interact with the following API model objects when using the Config APIs:
  • Account
    • Zone
      • Polygon
      • Circle
      • Bounding box (Rectangle)
      • Geoline
      • Beacon
      • Message
      • URL
      • Time Active
      • Date Range
      • Travel Path
      • Travel Direction
      • Speed
      • Geofeature
      • Action
      • Condition
    • Session
    • User
    • Project
    • Beacon

Config API Spec

You can view the actual API spec here.