Authentication

Management and creation of API tokens.

Authentication Flow

Application view of how a typical token request is made.

Upon integrating with gateway for the first time, there is no pre-existing API token for use. It must be generated with a physical button press on the gateway.

1. Press gateway button once. After that, there is a time window of 2 minutes to allow generation of API Token.
2. Call GET /api/v2/accesstoken/generate to generate a token. If time window has not expired, a token will be generated.
3. Store token safely for usage.
4. Use stored token in Authorization header for [SECURED] requests. (e.g. Authorization: Bearer [TOKEN])

🚧

Tokens will not be shown again!

Once a token is generated, it will not be shown again for security purposes. As a result, it is the responsibility of the client to remember/store the API token so that it can be used and destroyed if necessary.

Once an API token is generated, it is possible to use the token for all clients or generate new tokens dynamically under the authorization of a pre-existing token. This could be used for a potential master-slave relationship and allow clients to be revoked from accessing gateway.

API Token Usage

Any secured endpoint MUST provide token in Authorization field in request headers. There is an alternative when calling /api/v2/websocket due to javascript API browsers and other libraries not supporting additional headers. (See WebSocket for details)

A typical Authorization header looks like this:
Authorization: Bearer 2822de5c6d5fa78112230feb82798d55a7086f486db607e3

If coming from v1 API, the Authorization type (Bearer) has changed from Basic. Additionally, the token that is generated is used without any additional encoding.

Errors

If authentication is unsuccessful or [SECURED] endpoints are accessed without authentication, the following errors will be shown:

400 Bad Request

Returns if Authorization header is malformed.

JSON

{
  "status": 400,
  "returnCode": -1,
  "message": "Invalid formatted Authorization header value. Must be Bearer ACCESS_TOKEN."
}

401 Access Denied

Returns if access token is invalid or no attempted authentication on a [SECURE] endpoint.

JSON

{
  "status": 401,
  "returnCode": -2,
  "message": "Access denied using provided token or no access token provided."
}