Device Service API
The Device Service is used to keep track of the different devices directly visible to Clearance. Use this API to manage them.
Device Service Interactive Documentation
Required Security Policies
Special permissions are required to perform any operation from this API. Access can be granted to a user by following the procedure below.
- Open the Configurations page.
- Select the Security policies tab.
- Add the user in the security policy named Manage devices.
Check if your permissions are sufficient
A user can verify if his permissions are sufficient to use this API by making a request to
/tenant/{tenantId}/device/canmanage
.
Add a New Device
New devices can be added with a simple call to the /tenant/{tenantId}/device
endpoint.
curl -X POST 'https://clearance-a-device.geneteccloud.com/api/v1/tenant/genetec/device' -H 'accept: application/json' -H 'Content-Type: application/json' -H 'Authorization: Bearer <some_token>' -d '{ \
"DeviceIdentification": { \
"SerialNumber": "1234", \
"Manufacturer": "genetec", \
"Model": "clearance", \
"CommonName": "guide-1" \
}, \
"DeviceType": "None" \
}'
Device deletion
While you can create as many devices as you wish, the API does not allow you to delete them. As such, devices should be added diligently.
Activate a Device
Devices are not active by default. This means that you cannot associate them to an officer or use them with the correlation engine. To activate them, send a request to /tenant/{tenantId}/device/{deviceId}/activate
.
curl -X POST 'https://clearance-a-device.geneteccloud.com/api/v1-private/tenant/genetec/device/1234/activate' -H 'accept: text/plain' -H 'Authorization: Bearer <some_token>'
The number of devices that can be active at any given time is limited per account. If the limit is reached, the request will fail.
Deactivate a Device
Devices can be deactivated at any given time. This can be useful in order to remain under the limit set for your account. To deactivate a device, send a request to /tenant/{tenantId}/device/{deviceId}/deactivate
.
curl -X POST 'https://clearance-a-device.geneteccloud.com/api/v1-private/tenant/genetec/device/1234/deactivate' -H 'accept: text/plain' -H 'Authorization: Bearer <some_token>'
Configure a Device
Managing configurations for devices can be challenging and cumbersome when you have many of them. To simplify this, Clearance includes a set of API endpoints to manage the configuration of a device. They provide a central location to store and distribute configuration data for your devices. Configurations should normally be updated according to what was saved in the system prior to uploading files to the system.
Credentials management
Credentials are usually required to obtain access to the content of a device. You can use Clearance to store and retrieve them.
Add new credentials
Credentials can be added with a call to the
tenant/{tenantId}/configuration/negociate
endpoint. See this section for details.
Credentials can be retrieved by performing a request to the /tenant/{tenantId}/credential
. Note that a unique identifier is generated using the model’s first 2 fields (i.e. SerialNumber
, Manufacturer
). Therefore, these fields must always be the exact same values for every call to ensure the device is correctly identified. A list containing the current credentials as well as any other pending credentials will be returned. An empty list will be returned if no credentials exist.
curl -X POST 'https://clearance-a-device.geneteccloud.com/api/v1-private/tenant/genetec/credential' -H 'accept: text/plain' -H 'Content-Type: application/json' -d '{ \
"DeviceId": { \
"SerialNumber": "1234", \
"Manufacturer": "genetec", \
"Model": "clearance", \
"CommonName": "guide-1" \
}, \
"DeviceType": "BodyWornCamera" \
}'
If you notice that one of the received credentials is invalid, you can communicate it to the system by invoking the /tenant/{tenantId}/credential/failed
endpoint.
curl -X POST 'https://clearance-a-device.geneteccloud.com/api/v1-private/tenant/genetec/credential/failed' -H 'accept: text/plain' -H 'Content-Type: application/json' -H 'Authorization: Bearer <some_token>' -d '{ \
"DeviceId": { \
"SerialNumber": "1234", \
"Manufacturer": "genetec", \
"Model": "clearance", \
"CommonName": "guide-1" \
}, \
"Credentials": [ \
{ "DeviceCredential": "credential-1" } \
] \
}'
Configuration negotiation
The API provides two different ways to attach data to a device: Capabilities and Configuration. Capabilities are commonly used by devices to share some intricate information to the system. For example, you can use them to indicate the amount of space available on a device. On the other hand, use the Configuration field to push updates to your devices.
Adding or updating a configuration requires what we call a negotiation. It's a two-step process that starts with an initial call to the /tenant/{tenantId}/configuration/negociate
endpoint.
curl -X POST 'https://clearance-a-device.geneteccloud.com/api/v1/tenant/genetec/configuration/negociate' -H 'accept: text/plain' -H 'Content-Type: application/json' -H 'Authorization: Bearer <some_token>' -d '{ \
"DeviceId": { \
"SerialNumber": "1234", \
"Manufacturer": "genetec", \
"Model": "clearance", \
"CommonName": "guide-1" \
}, \
"DeviceType": "BodyWornCamera", \
"Capabilities": { \
"some": "data" \
}, \
"Configuration": { \
"some": "configuration" \
}, \
"Credential\": { \
"DeviceCredential": "some_credentials_to_update" \
} \
}'
Capabilities
Capabilities are updated right away. Any call to
configuration/negociate
will overwrite the current capabilities.
If the current configurations are exactly the same as the one stored on the server, a 304 Not Modified
status code will be returned. Otherwise, the expected configuration and a transaction id will be returned. If the device is able to apply these configurations, you must then commit the transaction. Committing a transaction is the only way for the configuration to become effective. To so, perform the following operation.
curl -X POST 'https://clearance-a-device.geneteccloud.com/api/v1/tenant/genetec/configuration/commit' -H 'accept: text/plain' -H 'Content-Type: application/json' -H 'Authorization: Bearer <some_token>' -d '{ \
"DeviceId": { \
"SerialNumber": "1234", \
"Manufacturer": "genetec", \
"Model": "clearance", \
"CommonName": "guide-1" \
}, \
"TransactionId": "1234ABC" \
}'
TransactionId
Use the
TransactionId
received with the expected configuration.
If the device cannot apply the configurations, the device must call the reject endpoint with a ReasonCode
and a ReasonMessage
identifying the reason of the failure.
curl -X POST 'https://dems-dev-eastus-device.azurewebsites.net/api/v1/tenant/genetec/configuration/reject' -H 'accept: text/plain' -H 'Content-Type: application/json' -H 'Authorization: Bearer <some_token>' -d '{ \
"DeviceId": { \
"SerialNumber": "1234", \
"Manufacturer": "genetec", \
"Model": "clearance", \
"CommonName": "guide-1" \
}, \
"TransactionId": "1234ABC" \
"ReasonCode": "er2019", \
"ReasonMessage": "corrupted" \
}'
Updated almost 3 years ago