Without getting too technical, an API is a way for software to communicate with each other. We have implemented a couple features that allow third parties, such as call centers, to easily retrieve DaVinci Lock® information for units in your facilities. But in order to do so, we can’t just allow anybody to access this info. That’s where API Keys come in. It’s a way of locking your information behind a door with a key that only you and one other party has. So if you use a third party call center and they need to be able to give out unlock codes for your DaVinci Locks, you will need to give them some information so they can get those.
Here’s what they will need:
- API Key
- API Secret
- Facility API IDs for all the facilities associated with the API Key and that you want them to be able to access.
As the name implies, the API Secret should be kept secret. It is literally the key to all of your DaVinci Lock codes. We are not responsible for what happens if you lose control of this value. If you do however, you should immediately lock the associated API Key, create a new one, and then give that new one to the appropriate party.
You should NEVER give an API Key / Secret pair to more than one other party.
API Documentation, for those who want to get seriously technical, can be found here.
Creating and Modifying API Keys
From the dashboard, click the API Settings tile at middle-right. You will see a screen which looks similar to this:
Click on Create API Key at the top-right and you will be shown a popup.
There are three things to do here.
- In the Name field, enter a descriptive name for the key. This should be something that helps you identify the purpose of the key. For example, “Call Center”. These names are not unique and are only used to serve as a human readable identifier.
- Under Facility, select the facilities you’d like the key to be able to access. You must select at least one facility for the key to be able to access anything.
- Click Save to create the key.
You will then see a new entry in the list of keys.
This list view will give you half of the necessary information. The API Key shown here is more or less public information. You should still safeguard it, but by itself nobody can access anything. In order to get the other half of the puzzle, click the edit button and you will see the edit popup. Click on Click to Show in order to see the API Secret. You can then copy the keys from this window and send them to the one party that needs to know them.
You can also modify which facilities the key has access to if necessary.
If the API secret becomes compromised, i.e. publicly available, you should disable it and create a new key. In order to do so, simply click the lock icon in the list of API keys for the compromised key.
Retrieving Facility API IDs
From the API Settings screen, you can get the facility IDs the API uses to reference your facilities. You don’t have to do anything to generate these. They are automatically created whenever a facility is created.
Toggling Facilities for inclusion or exclusion in the API
All facilities are included in the API by default. But sometimes you might want to exclude them. Perhaps they were made on accident, or are test facilities that aren’t actually real. Whatever the reason, you can do so here. Just click the green toggle switch and confirm the change.
Note: Excluding a facility from the API will also remove it from the customer portal.