Starting with version 1.2 of the API we have a new Manage Access endpoint, this endpoint removed the need to manually create users and keep track of user state.
Input arguments
The Manage Access endpoint accepts 4 arguments
delete - Array of AccessKey items to remove.
insert - Array of AccessKey items to insert.
sendPush - Optional, Should we send a push message to the user about the update.
sendInvitationEmail - Optional, Should we send an invitation email to the user. This value will be overridden if the user was created and no password was supplied. Then we will always send an invitation email with a one-time password.
The delete and insert arrays should include an AccessKey item, which should include an access object and a user object.
access
This object is a reference to the Access you want to give access too. You can either supply an accessId or an aliasId. What you should use depends on how you want to integrate with us. Either you can make the mapping to an access id yourself by fetching all possible accesses with the Get Accesses endpoint and then you save the mapping between your resource and the accessId in your system. The second alternative is that you let us do the mapping by adding an aliasId in Parakey. The aliasId could, for example, be the id of your resource (room id), then we will do the mapping in Parakey. The aliasId needs to be a unique id. We, therefore, recommend against using simple words, if you want to use a common word please use a prefix to make them unique to your integration. Read more about aliases.
user
This object could either reference an existing user by user id or an email address. If using an email address we will create the user if they do not exist. You can also supply optional user properties, for example first and last name, roles for this user, tags, language, or a predefined password. We will never override an existing user's name or password.
There are also 4 optional parameters for each item
startDate
From what date should this access by valid, Date and time in UTC, ISO 8601expirationDate
Date when this access should expire. If you want the access to be valid until you remove it leave the expirationDate empty. We do not recommend to set a sliding expiration (for example +10 years) since this will mean the key will actually expire in the future.aliasTag
Alias tag for this group of users. This can be used as a filter to remove all users within the same booking id for example.onBehalfOf
Some kind of identifier for what user-triggered this request, could be the user email, user id, or name of the user. Useful when the action is triggered by a specific user (for example calendar bookings), we will show this in the log for this individual AccessKey.
Give access to a user
Giving access is simple, you only need to tell us what Access and to which user, see additional optional parameters in the API docs. This should always be an array of objects.
{
"insert": [{
"access": {
"id": "2IhciBE7st"
},
"user": {
"email": "[email protected]",
"firstName": "Emil"
"lastName":" "Svensson"
}
}]
}If you want to give the user time-restricted access, simply include a start/expiration date in your request and the access will be limited to this time period.
{
"insert": [{
"access": {
"id": "2IhciBE7st"
},
"user": {
"email": "[email protected]"
},
"startDate": "2019-01-01T00:00:00.000Z",
"expirationDate": "2019-12-31T00:00:00.000Z"
}]
} A user can have an unlimited number of keys and we will always grant the user access to total time combining all start and expiration dates.
Remove access from a user
Removing a user is just as simple, we will remove every access that matches the delete criteria. The following example will remove all access from [email protected] and the access with specified access id.
{
"delete": [{
"access": {
"aliasId": "2IhciBE7st"
},
"user": {
"email": "[email protected]"
}
}]
}If you do not include start/expiration date all access will be removed regardless of their start/expiration date.
If you want to remove a key with a specified start/expiration date you can include this in the delete and we will only remove access matching that start/end date.
{
"delete": [{
"access": {
"aliasId": "2IhciBE7st"
},
"user": {
"email": "[email protected]"
},
"startDate": "2019-01-01T00:00:00.000Z",
"expirationDate": "2019-12-31T00:00:00.000Z"
}]
}In the response, you will get a deletedCount property indicating how many AccessKeys were deleted. This could be 0 if no AccessKey is found with the same start/expiration date.
Update access to a user
To update users' access you simply combine both delete and insert. We will then make sure that the users' access is updated accordingly. The following example will first remove any existing access from the user with the given Access Id. Then grant access starting 1 Jan 2019 to the last of Dec 2019 to the same Access id.
{
"delete": [{
"access": {
"id": "2IhciBE7st"
},
"user": {
"email": "[email protected]"
}
]},
"insert": [{
"access": {
"id": "2IhciBE7st"
},
"user": {
"email": "[email protected]"
},
"startDate": "2019-01-01T00:00:00.000Z",
"expirationDate": "2019-12-31T00:00:00.000Z"
}]
}
Create a completely stateless integration
There are two main ways to integrate with Parakey
Store the Domain Id and Access id for each resource in your system. Display a dropdown menu in the administration where you let the user select what "Key" to use in Parakey (using the Get Accesses endpoint).
Create a stateless integration by using Alias Id and Alias Tags. This way there is no need for any UI changes instead they will add your unique Id in the Alias Id field in Parakey. And for bookings, you can supply the Alias Tag property to simply update and remove bookings when needed.