API V1 represents a major upgrade in security, capabilities, and supported use cases over V0. API V1 has been available for partner use since September 2016, and we are requiring all customers to upgrade before a V0 decommission date (September 30, 2021).
This guide will go over the following functions:
- Registering a lock
- Retrieving a list of locks
- Creating an access guest (previously named “guest code”)
- Deleting an access guest
- Locations (previously named “properties”)
- Resort locks
In V1, we decided to move to a much more secure authentication protocol, named OAuth 2.0. It allows our customers to have complete control over their RemoteLock data. In V0, a simple username/password with authentication token implementation was in place, which required our users to change their credentials to revoke third party access.
Registering a lock
In V0, the model_id was chosen from a static list in the API docs:
In V1, the list of models is retrieved dynamically via an endpoint. When registering a lock, the model_id in the payload should match a model id returned from the models endpoint.
Setting attributes, such as the programming code, can now only be done via the update endpoint.
Retrieving a list of locks
In V0, a property ID was required to retrieve a list of locks. In V1, you can simply call /devices to retrieve all devices or /devices?type=lock to retrieve only locks.
Creating an access guest
In V1, we renamed “guest code” to “access guest” because an access guest represents a person. This person can also have multiple types of credentials, not just PIN codes.
Access guests also attained a fundamental shift in its ability: they are no longer tied/associated to a single lock. In fact, they can be granted access to a single lock, multiple locks, a group, or even a location. Our getting started page is a great resource on granting access.
The starts_at and ends_at datetime attributes of an access guest now require the ISO 8601 format.
Deleting an access guest
In V0, deleting an access guest (previously “guest code”) required passing the property and lock ID’s. This is no longer required. We also introduced the ability to deactivate (vs delete) an access guest.
In V1, we renamed “properties” to “locations”. We also required the time_zone attribute to be set. This is because any device/lock will receive its time zone setting from its location.
In V1, registering a resort lock is no different than registering other types of locks. However, a fundamental difference from V0 is resort lock guests are now their own entity. They are not access guests and are entirely managed through the /resort_lock_guests endpoint.