Device Discovery

Setting up a new device for consuming the Satellite Tag REST API is a four steps process:

1. Log into the backend and browse to the Device Discovery page

2. Open the Satellite Tag app and scan the QR Code [1] you see on that page

3. Enter a unique code [2] in the Satellite Tag app when you are prompted to and hit Connect

4. Click on Add when you see the unique code you just entered showing up on the Device Discovery page

[1]

The QR Code is nothing more than a URI to the POST /device-request/new API method that the Satellite Tag app will hit to announce itself.

[2]

Usually the app unique code is the 2-4 digits code on the back of the device. Because this code must be unique if you need to use it for multiple apps on the same physical device you must add a suffix (preferred) or prefix to it. For example, if 80 is the unique code printed on the back and you need two separate apps running on the same device, registration app and session gate app, then you could use 80REGO and 80GATE to uniquely identify them.

POST /device-request/new

Sends a new device discovery request to the server. If the request is accepted in the backend the response will expose API credential and common settings for up to 10 minutes after the request is first accepted.

You must send two parameters with this request, they are both required:

• code the unique code

• secret a random secret code

You will get back some useful information, possibly the most useful being apiUrl, that is the base URL you need to prefix to all API methods documented here.

Note

For this method to work you must log into the backend and browse to the Device Discovery page. Every time such page is loaded or refreshed the availability of this method is prolonged by 5-10 minutes.

Example request:

{
  "code": "83A",
  "secret": "owsso0wssogksk4s8gwg4gksw4w0"
}

Example response (before approval):

{
  "id": 24,
  "code": "83A",
  "secret": "owsso0wssogksk4s8gwg4gksw4w0",
  "agent": "insomnia\/5.7.14",
  "apiUrl": "https:\/\/example.com\/api",
  "createdAt": "2017-10-03T10:17:55+13:00",
  "updatedAt": "2017-10-03T10:17:55+13:00"
}

Example response (after approval):

{
  "id": 24,
  "code": "83A",
  "secret": "owsso0wssogksk4s8gwg4gksw4w0",
  "agent": "insomnia\/5.7.14",
  "apiUrl": "https:\/\/example.com\/api",
  "clientId": "13_1xxh5y6rxwzog8ksgswck8w0k8ok0k8ksos48s0c8wk4ko488k",
  "clientSecret": "3z0igne72b288ksg0w80wwkk048ocokcowws4coksskg00w0oc",
  "clearedAt": "2017-10-03T10:07:39+13:00",
  "clearedStatus": "added",
  "createdAt": "2017-10-03T10:07:20+13:00",
  "updatedAt": "2017-10-03T10:07:40+13:00"
}

If the unique code you are trying to use has been used already you will get back an error. This error should be shown back to the user so they can choose a different code. The error will look like this:

{
  "code": 400,
  "message": "Code already registered",
  "errorCode": 0
}

If the device discovery feature is disabled you will get back an error:

{
  "code": 503,
  "message": "Service Unavailable",
  "errorCode": 0
}