Access Groups

Access groups allow you to create groups of locks and people, where every user in a group get a key to every lock in the group. This make it more efficient to create and revoke keys when several people need access to the same locks.

An example of this could be different entrances in a residential building, or a specific company within a commercial building.

• If the Access Group have 5 people and 10 locks, there will be created one Key for each User on each Lock – in total 50 Keys.
• Access Groups are limited to have a maximum of 100 000 Keys, which is calculated as the product of Users * Locks. This means that you can have 20 Locks and 5000 Users, or 100 Locks and 1000 Users.
• While the maximum number of Keys in a group is limited to 100 000, there is a second 10 000 Keys limit which restricts how many Keys that can produced in a single API call. This is done to prevent overloading the underlying vendor systems.
• Access Group Keys can not be revoked through the normal Revoke Keys endpoint. Keys can only be revoked by removing the relevant User or Lock from the Access Group.

Create an Access Group

You can add an Access Group to your Project using the Create Access Group endpoint. Upon creation you can add Locks and Users right away, or you can add them later.

This is an example payload for creating an Access Group:

// POST /v2/projects/{projectId}/access-groups
{
        "name": "Test Access Group",
        "description": "Test Access Group Description",
        "lockIds": [lock1.id, lock2.id],
        "appUserIds": [user1.id, user2.id],
}

The endpoint validates if the provided appUserIds are valid phone numbers, and if the lockIds refer to Locks within your Project. If everything is valid, the Access Group is created and Keys are created.

The product of lockIds.length and appUserIds.length can not exceed 100 000, which is the maximum number of Keys we allow being created in one go.

Updating an Access Group

There are two different endpoints for updating Access Groups. Update Access Group can be used to update name, description and metadata. Then there is a separate endpoint to to update what people and what Locks should be in the group called Update Access Group Accesses. This endpoint accepts four lists at the same time, with users to add and remove, and locks to add and remove:

// POST /v2/projects/{projectId}/access-groups/{accessGroupId}/update-accesses
{
  "appUserIdsToAdd": [
    userId1,
  ],
  "appUserIdsToRemove": [
    userId2
  ],
  "lockIdsToAdd": [
    lockId1, lockId2
  ],
  "lockIdsToRemove": [
    lockId3
  ]
}

• Only one call to this endpoint is allowed at the time – the platform acquires a mutex during the operation, and releases it when the job is done.
• The sum of "Keys created" and "Key revoked" by doing this operation can not exceed 10 000.

Deleting an Access Group

Delete an Access Group using the Delete Access Group endpoint.

// DELETE /v2/projects/{projectId}/access-groups/{accessGroupId}

This will revoke all Keys that have been created by adding Users and Locks in this Access Group.

Access Groups Keys

Keys created through an Access Group will be associated with the Access Group and the id and name of the Access Group will be embedded on the Key when read from the API.

These Keys can not be revoked through the regular Revoke Key endpoint. The only way to revoke a Key created by an Access Group is to either remove the relevant App User or Lock from the group.

Access Groups in the Unloc Control Center

You can find and manipulate your Access Groups in the Unloc Control Center.