Device Discovery

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

1. Log into the Control Room and browse to the Device > Discovery page.

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

3. Enter a unique code [2] in your 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, check-in app and access control app, then you could use 80CHECKIN and 80ACL to uniquely identify them.

        sequenceDiagram

  participant Mobile App
  participant TAG API
  participant Control Room

Control Room ->> Mobile App: Display QR Code
Mobile App ->> TAG API: POST /api/v5/device-request/new
TAG API ->> Control Room: Display request
Control Room ->> TAG API: Approve request
TAG API ->> Mobile App: Send OAuth2 credentials
Mobile App ->> TAG API: POST /api/oauth/v2/token
TAG API ->> Mobile App: Send OAuth2 access token

Mobile App ->> TAG API: POST /api/v5/device/ping
TAG API ->> Mobile App: Send TAG config response

loop frequency as per config
Mobile App ->> TAG API: POST /api/v5/device/ping
TAG API ->> Mobile App: Send TAG config response
end
    

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 can also send a preferredType parameter, specifying the type of your app. This can be project specific, but some predefined types, recognised by all TAG instances are: checkin, accesscontrol and upload.

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.

See the list of Error Responses for more information, in particular errors 1001 and 1002.

Example request:

{
      "code": "INSOMNIA",
      "secret": "B7HmsMiUbl18Bk3Lx1Yo",
  "preferredType": "accesscontrol"
}

Example response (before approval):

{
  "data": {
    "id": 14,
    "code": "INSOMNIA",
    "secret": "B7HmsMiUbl18Bk3Lx1Yo",
    "agent": "insomnia\/2023.5.8",
    "createdAt": "2023-09-27T13:30:50+13:00",
    "updatedAt": "2023-09-27T13:30:50+13:00",
    "apiUrl": "https:\/\/localhost:8000\/api"
      },
  "meta": {}
}

Example response (after approval):

{
  "data": {
    "id": 14,
    "code": "INSOMNIA",
    "secret": "B7HmsMiUbl18Bk3Lx1Yo",
    "agent": "insomnia\/2023.5.8",
    "deviceId": 53,
    "clientId": "28b7...20e6",
    "clientSecret": "88ea...0c8b",
    "clearedAt": "2023-09-27T13:31:10+13:00",
    "clearedStatus": "added",
    "createdAt": "2023-09-27T13:30:50+13:00",
    "updatedAt": "2023-09-27T13:31:10+13:00",
    "apiUrl": "https:\/\/localhost:8000\/api"
      },
  "meta": {}
}

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:

{
      "data": {},
  "meta": {
    "error": {
      "code": 409,
      "message": "This code has been discovered already. Use a different code, or append something to it.",
      "internalCode": 1002
    }
  }
}

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

{
  "data": {},
  "meta": {
    "error": {
      "code": 503,
      "message": "Device discovery is not accepting requests at this time. Contact an administrator for help.",
      "internalCode": 1001
    }
  }
}