Short intro to core concepts

To gain a better understanding of how to utilize the Unloc Platform, let's take a tour of some of the important concepts.

This diagram shows how Locks belong to an Organization, and are grouped into Projects.

Organization

An Organization is the top entity in the Unloc platform.

  • The organization is a customer of Unloc, that uses the Unloc API or the Unloc Control Center to manage mobile keys.
  • An Organization organizes it's work in one or more Projects.
  • All Organizations can log into the Unloc Control Center to see an overview of all Projects. Here, they can also create new Projects.
  • An Organization can create their own integration using the Unloc API, or use use third-party applications to manage their mobile keys.

Project

A Project is an entity used to logically contain your work. It includes Locks, Managed Users, Keys, Sharing Rights and more. A Project can vary in size – it's entirely up to you. It can be as small as a building or as large as a city. The size of your Project should be determined by how you manage access.

If you are a BBL where separate co-ops are managed by independent boards, and no one should have keys to multiple buildings, then creating one Project per co-op might be a good idea.

If you're a Property Manager who oversees many properties and needs to provide service personnel with access to different doors across these properties, then it might be more suitable to create one large Project.

Opening doors

Locks and Keys

The Lock model is the representation of a physical Lock. Each Lock belongs to one Project, and one Project only. All Keys for this Lock are created within the context of this Project.

To enable a user to operate a Lock, you need to create a Key. A Key gives a user the ability to open (and close) doors. Keys are used in the Unloc App, and become available to the user as soon as they log into the app.

A Key represents a user's ability to lock and unlock a Lock. Keys are visible to the user in the app.

Keys can be permanent (until explicitly revoked), or they may only be active during a specific period, which means they may be restricted to only work during specific time frames within a day.

A Key is sent to and associated with a Mobile Phone number and does not require the user to exist at the time of creation. This makes it easier to distribute Keys as users do not need to have the Unloc app installed on their mobile devices beforehand.

Sharing Rights

A Sharing Right represents a user's ability to share Keys with other users for a specific Lock via the Unloc App. This right does not grant the ability to open a Lock, but it is often granted in conjunction with a Key.

A Sharing Right is given to a Mobile Phone Number, and does not require the user to have created an account via the Unloc App at the time of creation.

When a Sharing Right is removed, all keys created with the Sharing Right will also be removed.

App Users vs. Managed Users

In the data model we distinguish between App Users and Managed Users. Despite representing the same individual, these terms signify two different user representations. Both will be associated with the same mobile number.

  • An App User refers to a user logged into the app, displaying the name and image that the User has set.
  • In contrast, a Managed User represents a user as defined by you, which allows you to assign a name and add metadata relevant to your Project.
  • If you create a key for a user under two different Projects, you will create one Managed User per Project for the same user. The user can have different names and metadata in the different Projects.

When using the Unloc API, you will refer to both App Users and Managed Users, depending on the endpoint.

In the documentation, when we refer to a user, it is the individual with a phone in hand we are addressing. When discussing the Managed User, we will explicitly use this term.

Where do Locks come from?

A lock connection represents the connection between a Project and a lock vendor (such as Danalock, Master Lock or Futurehome, for instance). A Project gains access to all the Locks available through any of it's Lock Connections.

A Project may have multiple Lock Connections. However, a vendor account may only be linked to a single Project.

You can onboard a new Lock Connection directly in the Unloc Control Center, or use the API to create your connection. Alternatively, you can seek assistance from installers.

Bringing it all together

An Organization can contain many Projects, and each Project will hold Locks, Keys and Sharing Rights.

Service Providers

In contrast to an organization, a service provider does not own their own Locks. They get access to Locks owner by others.

The Service Provider API is not released in Version 2 yet, so please refer to the Version 1 guide and API reference.