Using the BlueID Operator API

Requirements

To access the BlueID Operator API, you need to prove your authorization using HTTP Basic Authentication and entering your operator user name and password which you received from us. Please bear in mind that your user name and your API key are two different things!

API Documentation

The basic URL for the Operator API is: https://<hostname>/operatorapi/ For the integration environment for example, it is https://operatorapi-int.blueid.net/operatorapi.

You can find an interactive HTML description of the BlueID Operator API here: https://<hostname>/operatorapi/apidocs/index.html For the integration environment for example, it is https://operatorapi-int.blueid.net/operatorapi/apidocs/index.html.

The BlueID Operator API is a RESTful service, which means that every call is stateless and contains all the information needed to fulfill the request. From Release 3.0 onwards only JSON is supported.

You can find the full description in the BlueID Operator API manual, but we will now explain some basic functionality here. Instead of writing a REST client on your own, you can go on and play with the BlueID Operator API using a REST plug-in for your favorite desktop browser like "Advanced Rest Client" for Google Chrome or "RESTClient" for Mozilla Firefox.

Examples

Getting the details of a Secured Object

GET https://<hostname>/operatorapi/securedobjects/<securedObjectId> Then you will receive something like:

{
 "id": "aH9mn30z39",
 "channels": ["btlespp"],
 "urls": ["btlespp://ESHNGU8J/00005301-0000-002a-426c-756549442a00"],
 "creationTime": 1405085828000
}

Please note that the URL for the channel btlespp is of the form btlespp://<localName>/<UUID>. We recommend saving the BLE local name and UUID for each secured object in your system.

Creating a BlueID Token

POST https://<hostname>/operatorapi/tickets The BlueID Operator API needs to know details about the BlueID Token to create, so we need to provide a payload:

{
 "securedObjectId": "ffoT319GYa", 
 "mobileDeviceId": "yjo03OJDWk", 
 "beginDate": 1406880000000,
 "endDate": 1409472000000,
 "commands": ["tokn"],
 "channels": ["btlespp"]
}

beginDate and endDate are UNIX timestamps (in milliseconds) that start on 1970-01-01, so hereby we create a BlueID Token that starts on 2014-08-01 8:00 UTC and ends on 2014-08-31 8:00 UTC. It is a BlueID Token issued to the mobile device with ID yjo03OJDWk so that it can use the command tokn via Bluetooth low energy (channel btlespp) on the secured object with ID ffoT319GYa.

If successful, the BlueID Operator API returns 201 Created and sends a header called "Location" which provides you with information about that BlueID Token.

Querying BlueID Tokens for a Secured Object and showing BlueID Token details

GET https://<hostname>/operatorapi/securedobjects/<securedObjectId>/tickets In return you will receive a list of BlueID Token IDs that were created for that particular secured object. To view the token details, simply call

GET https://<hostname>/operatorapi/tickets/\<ticketId\> The result will look like this:

{ "id": "ABuBt4pr9lhf", "securedObjectId": "pMtOS7q0lT", "mobileDeviceId": "676qPIMBcK", "beginDate": 0, "endDate": 1533821000000, "creationDate": 1409318548000, "commands": ["open", "clos", "tokn"], "channels": ["btlespp"], "status": "VALID" }

In this example, we see a valid BlueID Token (status is "VALID", no revocation date given) which has not yet been downloaded to the corresponding mobile device (no download date given). This BlueID Token is valid from 1970-01-01 (beginDate is "0") until 2018-08-09 13:23 UTC (endDate is "1533821000000"). The BlueID Token itself was created on 2014-08-29 (creationDate is "1409318548000") for a mobile device with ID 676qPIMBcK. It allows control of the lock server with ID pMtOS7q0lT by btlespp channel with commands open, clos and tokn.