We are excited that you are interested in our API. The Parakey API is a great tool to integrate Parakey into your own service and distribute mobile keys. This document will serve as a getting started and once you have read this document you can head over to the API specification (api documentation) where all endpoints and examples are documented.
- To become a developer you need to have a Parakey account. Before you proceed please contact me at firstname.lastname@example.org and I will set up an account for you to get started.
- Sign in to My Parakey with the development account you just created.
- Make sure that the account you are using has the role "API Administrator" on the Domain you want to manage. If you are using your Demo Domain you can set this yourself, once you want to integrate with a real customer you need to ask them to make you an "API Administrator" for their Domain as well.
- Follow the steps in the Authentication article on how to create an Access-Token.
- Create a new Key that will be distributed with your app. We always recommend that you distinguish the Keys distributed by your app with already existing keys that might be used manually through My Parakey. A good way to do this is to create a key and name it with your app/company name. For example, if there already is a key to with the name "Front door", you simply create a new key with the same properties called "Front door (My integration)". Find the AccessId for this Key and write it down so you can use it later when creating AccessKeys.
Awesome, you are now ready to integrate with our API! There are two main endpoints that you will be integrating with, first is to create an AccessKey and to revoke AccessKeys. When you send a request to create an AccessKey we will automatically create a new user account if the users don't exist and send them an invitation email. If the users do exist we will send a push message to their phone and the key will be available in an instance.
Important! We have noticed that people might be confused when they get the invitation email if they haven't been informed that you are using Parakey to distribute mobile keys. So please make it as clear as possible when the user is interacting with your system that the key will be distributed using Parakey. For example by using our logo next to the booking button.
All requests shall be done over HTTPS to https://api.parakey.co, the relative path prefix /v1.x indicates the version of the API. We will only change the version prefix on major API changes with possible breaking changes.
To send a new key use the Add AccessKey endpoint and supply the following attributes
- Email address to the user
- Domain ID - ID to the Domain you are using
- Access ID - ID to the Key you created earlier
- Start date - When the key will be valid from (optional)
- Expiration date - When the key will expire (optional)
We do not recommend using sliding expiration dates (for example new Date() + 10 years), instead leave expiration date empty. The expiration date should only be used with a fixed expiration, for example, a contract that ends on 1 January, or a booking that is only valid for 3 hours.
An HTTP 200 response indicates that the key has been created, the response will include an AccessKey ID, you do not need to save this ID. Sending the same request again will not create a new AccessKey simply return the existing one, and removing an AccessKey can also be done using the same parameters and we will remove any matching Keys.
If you want to remove access for your user you need to delete the AccessKey you have created. This can be done by using the AccessKey ID but we recommend using the same attributes as when you created the key.
We do not recommend using the delete user endpoints unless you are certain that the user should no longer have any access. Since this will also remove any other keys that this user has (for example, owners might have keys that are manually distributed with My Parakey). This might also be limited in the future and throw an error. So you are better off using delete AccessKey instead.
An HTTP 200 response indicates that the key has been revoked, you might also get an HTTP 404, meaning they key has already been removed. This should also be interpreted as a valid response and you should not retry on 404 errors. The key might have been removed manually by an administrator through My Parakey.
Changing an AccessKey
You can not change an AccessKey, instead, you need to remove the previous one and send them a new one. Every change will by default generate a push message to your user. To make sure not to spam users we recommend that you use the sendPush=false attribute on the delete AccessKey call and sendPush=true when creating the new one. That way your user will only receive one push message for the "change".
How do I find the ID for X?
As an API Administrator, you can always find the ID for your resources in My Parakey. Simply sign in to your account and follow these steps.
- domainId: Navigate to the Developer page by pressing the Development button in the top right corner (only visible if you are an API Administrator). Here you will find a list with all the Domains with the corresponding ID that you have access too.
- accessId: Navigate to the Keys page, click on the row for the Key you are interested in. On the details page that is displayed on the left, scroll all the way down and you will find the AccessId printed in gray.
Can I unlock the door with the API?
The API is only an integration with the Parakey mobile key distribution platform, to unlock the door the user will always need to use the Parakey app. The app uses Bluetooth to connect to the Parakey hardware to unlock the door.
How to test the integration
Once you are ready to start integration we will create a demo Domain account for you to use, you can try all API features and sign in to My Parakey to verify that keys are being created as they should. If you want an end to end test you need to purchase the Parakey hardware or try at your customer's location (if they have Parakey installed).
What can I build using the integration?
- Booking system - automatically send mobile keys that lets your members unlock the door during their current booking.
- Business system integration - Sync your member or employee directory and automatically distribute mobile keys to your employees.
- Calendar integration - Send a mobile key to unlock the meeting rooms for a specific timeslot.
- Guest notification - Send a message to the person who invited someone that notifies them when their guest has arrived and unlocked the door.