Guides

Device Service API

Suggest Edits

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

dems-proda-api.clearance.networkdems-proda-api.clearance.network
Swagger UI

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.

  1. Open the Configurations page.
  2. Select the Security policies tab.
  3. Add the user in the security policy named Manage devices.
1856

📘

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

799

Credentials management overview

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.

945

Negotiation overview

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 about 2 years ago