All Terso Devices of the Device Type Enclosure (which includes all freezers, fridges, and most cabinets) are secured and will only grant open when presented with a valid pass, which we call credentials. Configuring which passes can open which devices with the API takes several sequential steps, but following this guide will ensure that your access configuration goes as smoothly as possible.
Let's review the high-level steps to configure an enclosure's credentials list before we dive into the details:
- Create a list of pass credentials which can access a particular enclosure.
- Sync the credentials to the physical Jetstream device.
- Verify that the credentials you synced to the device are the only passes which are able to open the cabinet.
- Modify as needed.
Creating Device Credentials
Enclosure's must be assigned a list of pass credentials in Jetstream before that list can then be synced to the device. Use the Create Device Credentials endpoint, specifying the device name and the list of pass credentials you want to allow to access that device.
Syncing Device Credentials to a Device
At this point, Jetstream knows which pass credentials are allowed to access the enclosure, but the physical enclosure has not yet received the new list of approved credentials.
- For each device that has device credentials specified in Jetstream, use the Sync Device Credentials endpoint to apply the credentials as they are configured in Jetstream.
Only sync the credentials to a device when the device is online and able to receive the command. If the device does not receive the command within four hours, the command will time out and the credentials will not be synced. You can verify that a device is online using the Get Device Status command, an online device should respond with "websockets: enabled".
Reviewing Credentials in Jetstream and Synced Credentials
You have created a list of credentials for each secured device in Jetstream, and synced the credentials to those device. You can review the current state of credentials in Jetstream and on the physical device using different endpoints.
- Review a specific device's existing credentials list in Jetstream using the Get Device Credentials endpoint.
- Review the last time the Jetstream credentials list was synced to a device using the Get Last Device Credentials Sync Date/Time endpoint. This will allow you to determine if the list in Jetstream matches the list on the physical device. If the list in Jetstream was modified after the last sync time, a Sync Device Credentials should be made so that the Jetstream list matches the physical device list.
Changing a Device's Credentials
You have successfully created a list of credentials for an enclosure, and synced those credentials to the physical device. If you wish to change the credentials that can access a device at this point, you have multiple options, depending on your goal:
Modify Device Credentials
This option is best when you want to add additional credentials, or add and remove credentials simultaneously, to a device.
- Overwrite the device's existing credentials list in Jetstream using the Modify Device Credentials endpoint.
- Sync the new credentials list to the device, using the steps above.
Delete Specific Credentials
This option is best if you are only looking to remove specific credentials from a device.
- Specify the specific credentials you want removed from the device using the Delete Device Credentials endpoint.
- Sync the new, shorter, credentials list to the device, using the steps above.
Delete All Credentials
This option is best if you wish to quickly remove all credentials from a device, completely preventing anyone from opening the device. If you want to remove access to the device only temporarily (less than a week), consider using the Lock a Device endpoint instead.
- Use the Modify Device Credentials endpoint and pass an empty credentials array to overwrite all passes without having to specify each pass you want to delete.
- Sync the new, empty, credentials list to the device, using the steps above.