HR software integration guide

This will guide you through integrating your HR software with Akiles. Following this guide, your integration will allow the user to:

Connect their Akiles organization.
Configure HR software group -> Akiles group mapping.
Automatically sync employees to Akiles members.

Tip

Why map groups to Akiles groups and not to Akiles locks/doors? A few reasons:

Employees often need access to multiple doors. For example employees in the “Engineering” group might need access to “Street door”, “Engineering Floor” and “Super secret engineering vault”. A single group can configure access to multiple doors, so you can make your mapping “1 group = 1 group” instead of “1 group = N doors”, which is simpler to implement.
In Akiles, there’s no way to associate members to doors directly. You’d have to create a temporary groups for each employee with the right list of doors and delete it after. It’d be more work!
Groups have an advanced permission system that your users can take advantage of. If you manage doors directly you’d have to reimplement all of it from scratch.

User experience

Add a section for the Akiles integration. We recommend it shows the “status” of the integration: connected or not connected. When not connected, show a button the user can click to start the connection process. When clicked, redirect the user to the OAuth authorization flow.

Once connected, we recommend displaying the following:

The organization name the integration is connected to. You can obtain it from GET /organization.
Checkboxes for enabling/disabling the different credential types.
A section where the user can configure a mapping from each group in your software to an Akiles group.

Getting started

Create an application in the Developer Center.
Create a test organization in the Developer Center. We recommend you choose the “Office” template, it will fill the test organization with devices and groups corresponding to a typical office setup.
Implement the OAuth authentication to the point you can obtain an access token + refresh token for the test org.
Use the access token to do API calls as detailed below.

API calls

The goal of the integration is to sync employees to Akiles members. When employees are created or edited, do API calls to Akiles to create or update the corresponding member. Here’s a list of the API calls you need to do:

On employee created

POST /members
- name
- metadata: store the employee ID or another metadata you might want to use to find the member later.
POST /members/{id}/group_associations
- member_group_id: the corresponding groups according to the mapping.
Create credentials for the member, for the types the user enabled when configuring the integration:
- POST /members/{id}/magic_links
- POST /members/{id}/emails
- POST /members/{id}/pins
- POST /members/{id}/cards
If desired, send PIN/link to employee via your preferred method (email, SMS…)

On employee groups changed

Delete old member_group_associations. DELETE /members/{id}/group_associations/{id}
Create new member_group_associations with the new group ID. POST /members/{id}/group_associations

On employee delete

DELETE /members/{id} (immediately revokes all access)

No need to delete credentials or group associations, just deleting the member is enough.