Usage Record

Endpoints

Fetch All Usage Records

You can fetch all usage records in all rule sets for the logged in user. The usage record will include both active and inactive devices. This is done by running the following command:

curl -X GET \
"https://{tenant}.device.{domain}/api/v1/usages" \
-H "accept: application/json" \
-H "Authorization: Bearer {jwtToken}"

By default, devices which have already been deleted are filtered out. They can be displayed by attaching a filterDeleted=false query parameter, like so:

curl -X GET \
"https://{tenant}.device.{domain}/api/v1/usages?filterDeleted=false" \
-H "accept: application/json" \
-H "Authorization: Bearer {jwtToken}"

Responses

Response code	Description
200 OK	Usage records retrieved successfully
404 NOT FOUND	No usage records found for user

Example response:

{
  "data": [
    {
      "deviceUser": "724c4efc-11b4-4h32-g7d9-3532s463cave",
      "usages": [
        {
          "devices": [
            {
              "label": "My iPhone",
              "udid": "eb840180-4c23-11e8-842f-0ed5f89f718b",
              "lastUsed": "2020-10-28T09:02:02.292Z",
              "state": "ACTIVE",
              "initializationDate": "2020-10-28T09:02:02.287Z",
              "lastDeletion": "1970-01-01T00:00:00.000Z"
            }
          ],
          "lastDeletion": "1970-01-01T00:00:00.000Z",
          "ruleSetName": "default",
          "deviceUsageRestrictions": {
            "lockTime": 2592000000,
            "maxDevices": 5
          },
          "nextDeletion": "1970-01-31T00:00:00.000Z",
          "numActiveDevices": 1,
          "numDevices": 1
        }
      ]
    }
  ]
}

Fetch Usage Record for a Rule Set

Run the following command to retrieve the user’s usage record for the specified rule set. This will retrieve both active and inactive devices.

curl -X GET \
"https://{tenant}.device.{domain}/api/v1/usages/{ruleSet}" \
-H "accept: application/json" \
-H "Authorization: Bearer {jwtToken}"

Again, deleted devices are filtered by default and can be returned with the filterDeleted=false query parameter.

Responses

Response code	Description
200 OK	Usage records retrieved successfully
404 NOT FOUND	No usage records found for user

Example response:

{
  "data": [
    {
      "devices": [
        {
          "label": "My iPhone",
          "udid": "eb840180-4c23-11e8-842f-0ed5f89f718b",
          "lastUsed": "2020-10-28T09:02:02.292Z",
          "state": "ACTIVE",
          "initializationDate": "2020-10-28T09:02:02.287Z",
          "lastDeletion": "1970-01-01T00:00:00.000Z"
        }
      ],
      "lastDeletion": "1970-01-01T00:00:00.000Z",
      "ruleSetName": "default",
      "deviceUsageRestrictions": {
        "lockTime": 2592000000,
        "maxDevices": 5
      },
      "nextDeletion": "1970-01-31T00:00:00.000Z",
      "numActiveDevices": 1,
      "numDevices": 1
    }
  ]
}

Register Device

This is the command to register a device. The service will first check that the device passes all rules and responds accordingly.

curl -X POST \
"https://{tenant}.device.{domain}/api/v1/usages/{ruleSet}" \
-H "Authorization: Bearer {jwtToken}" \
-H "Content-Type: application/json" \
-d '
{
 "label": "My iPhone",
 "udid": "eb840180-4c23-11e8-842f-0ed5f89f718b"
}
'

Responses

Response code
200 OK	Existing device accepted
201 CREATED	New device accepted and registered
400 BAD REQUEST	Request was malformed.
403 FORBIDDEN	Device was denied
404 NOT FOUND	Rule set does not exist, and no default rule set was found

Check Device

You can also check if a device passes the rules without registering it. Run the following command:

curl -X PUT \
"https://{tenant}.device.{domain}/api/v1/usages/{ruleSet}" \
-H "Authorization: Bearer {jwtToken}" \
-H "Content-Type: application/json" \
-d '
{
 "label": "My iPhone",
 "udid": "eb840180-4c23-11e8-842f-0ed5f89f718b"
}
'

Responses

Response code
200 OK	Device passes rules
400 BAD REQUEST	Request was malformed
403 FORBIDDEN	Device denied
404 NOT FOUND	Rule set does not exist, and no default rule set was found

Fetch Device

The following command retrieves information about the given device.

curl -X GET \
"https://{tenant}.device.{domain}/api/v1/usages/{ruleSet}/{deviceId}" \
-H "accept: application/json" \
-H "Authorization: Bearer {jwtToken}"

Responses

Response code	Description
200 OK	Device successfully retrieved
404 NOT FOUND	Could not find device

Example response:

{
  "data": [
    {
      "label": "My iPhone",
      "udid": "eb840180-4c23-11e8-842f-0ed5f89f718b",
      "lastUsed": "2020-10-28T09:02:02.292Z",
      "state": "ACTIVE",
      "initializationDate": "2020-10-28T09:02:02.287Z",
      "lastDeletion": "1970-01-01T00:00:00.000Z"
    }
  ]
}

Update Device

The following command updates the device label.

curl -X PUT \
"https://{tenant}.device.{domain}/api/v1/usages/{ruleSet}/{deviceId}" \
-H "accept: application/json" \
-H "Authorization: Bearer {jwtToken}" \
-H "Content-Type: application/json" \
-d '
{
 "label": "My new iPhone",
 "udid": "eb840180-4c23-11e8-842f-0ed5f89f718b"
}
'

Responses

Response code	Description
200 OK	Device successfully updated
400 BAD REQUEST	Request was malformed
404 NOT FOUND	Device not found

Example response

{
  "data": [
    {
      "label": "My new iPhone",
      "udid": "eb840180-4c23-11e8-842f-0ed5f89f718b",
      "lastUsed": "2020-10-28T09:02:02.292Z",
      "state": "ACTIVE",
      "initializationDate": "2020-10-28T09:02:02.287Z",
      "lastDeletion": "1970-01-01T00:00:00.000Z"
    }
  ]
}

Delete Device

By running the following command a user can delete their device if the usage record is not subject to a rule set’s lock time. The device will remain in the database flagged as deleted.

curl -X DELETE \
"https://{tenant}.device.{domain}/api/v1/usages/{ruleSet}/{deviceId}" \
-H "accept: */*" \
-H "Authorization: Bearer {jwtToken}"

Responses

Response code	Description
204 NO CONTENT	Device successfully deleted
404 NOT FOUND	Device not found