Skip to main content

Authentication

Things you’ll need to get started…

Before you can Authenticate with the Echolo REST API you will need three items:

Header Value

Description

appId (older API versions 1 & 2 use app-id)

The appId of your application.

secret

When your application is created, your secret is also given to you with your appId.

x-api-key

When your application is registered, an api-key is generated along with your appId and secret.

If you do not have the above-mentioned credentials, please create an account on the Echolo IoT Platform.

Authentication

This API employs a key-based authentication mechanism to ensure secure access to its resources. It is required that your application provides valid credentials in the header of each request. Prior to accessing the resources of the API, authentication must be performed by requesting an access token. This process involves exchanging your API Secret for a reusable token, which must be included in all subsequent requests alongside your app-id and x-api-key for successful access.

Tokens

Echolo REST API uses temporary tokens used to validate your request, in the process of working with this API you may run into the following errors.

Token Expiration - Access Tokens are valid for 2 hours, your application should catch authentication failures resulting from token expiration and handle requesting a new Access Token as needed.

Example of a token that has expired:

JSON
{
    "error": "Your application token has expired, please renew /token"
}

Example if a token that is not present in the header:

JSON
{
    "error": "Missing valid token."
}

Sample request for Token

JS
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.echolo.io/v3/application/token',
  headers: 
   { 'x-api-key': 'x-api-key',
     'app-id': 'appId', /// older API versions 1 & 2 use app-id
     secret: 'secret' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(JSON.parse(body.token));
});

Required Headers for Token Request

Name

Type

Description

appId (older API versions 1 & 2 use app-id)

String

Also known as your appId or application ID.

secret

String

After using the /token method this is attached to all requests.

x-api-key

String

A static key used to authenticate you with your token and app-id.


Sample token Response

The entire application object is returned when a valid token is created.

JSON
{
    "secret": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "createdAt": "2017-08-05T03:39:04.106Z",
    "appId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjcmVhdGVkQXQiOiIyMDE4LTAzLTE1VDAxOjUxOjM2LjgzOFoifQ.8Q7w3OVjINawWgBKNj2NnkVkhLiiZ0XxOf84vvMOyj4",
    "name": "My App",
    "updatedAt": "2017-03-15T01:51:36.904Z"
}

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.