Table Mockup 2 - Blue Multiply.jpg

API

 

THIS documentation is still under development

Parakey is not only a access control system, it is also an access control platform with a easy to use and powerful API. Allowing you as a developer to add physical access control to your product or service.

You tell the Parakey Cloud service whom shall have access, when and where - Parakey does the rest!

 

 
 

Introduction to Parakey

Parakey is built up by three things; a Cloud service, a smartphone-App and a sophisticated hardware. You as a developer can easily issue/revoke access (and much more) via the Cloud Service from the Parakey-API which automatically sends/removes an access key to the desired user's smartphone, so that the user can trigger the Parakey hardware to unlock a restricted area.

The smartphone-App automatically recognizes hardwares representing restricted areas, such as locked doors, which the user has access to and can unlock. The App does not require Internet connection during openings and uses Bluetooth LE to communicate with the Parakey hardware.

Access logs are generated when users unlocks restricted areas. These logs can you as a developer use to trigger actions in your own application and also have a track record on who got in when and where. 

 
 

Key elements of the API

The API is build up by a number of elements that is important to know to get a better understanding:

  • Domain - A domain is the top-level of a collection of accesses and their access keys. An office space could be a domain for example or a whole city.
     
  • Access - An access is one or a collection of hardwares. A hardware element is created when it is physically installed and describes the hardware's behavior, properties such as name and security level.
     
  • Access Key - An access key links a user to an access. In other words, the user gains access to restricted areas.
     
  • Role - There are a number of roles that controls which permissions a user has within a specific domain. Invite users and issue access keys are two examples of permissions.
     
  • User - A user is identified by its e-mail address. A user can have multiple roles, access keys and be linked to multiple domains.

 

The different elements are described into more detail below for further understanding or just head over to the API-documentation if you feel like a Pro.

 
 

Domain

A domain is the top-level of a collection of accesses and access keys. A customer/user can be linked to one or more domains but it is more common to have just one. A domain can be a rocking co-working space for startups or a whole city.

A domain has a user that is the owner and holds the permissions to handle billing, add administrative permissions to other users and so forth. When a user with administrative permissions logs in to my.parakey.co you are first prompted to choose the domain you want to administrate (if you are linked to multiple domains).

The ID of the domain is used to identify the domain from the API. 

 
 

Access

An access is one or a collection of hardwares. A hardware element is created when installed and describes the hardware's behavior, properties such as name and security level.

An access representing a single hardware (which in itself is controlling a door, gate etc.) is generated per default when a hardware is added to a domain, this access is named the same as the hardware (for example "Entrance" or "Kitchen Door").

Often it helps to group a collection of hardwares into an access element to simplify the process of issuing permission to unlock multiple restricted areas. 

An access element contains a number of properties such as;

  • name of the access, "All Doors" or "C-house" for example.
  • security level
  • valid time period which can be helpful when creating a specific access for "Summer Camp" that automatically shuts down all the access keys when the summer is over.
  • hardware references 

Access elements can only be created by users having "Administrator", "Installer" and/or "Owner" permissions.

 
 

Access Key

An access key links a user to an access. In other words, gives the user rights to restricted areas. This is the key that is automatically distributed and downloaded in the smartphone-App. The access key can be used "Offline" to unlock restricted areas.  

An access key inherits an access's (described in the section above) security level and name as well as the maximum valid time period. The valid time period of an access can be overwritten (and it often is) by setting a valid time period on the access key. Although the valid time period of the access key can not be longer than the maximum valid time period of the access.

Access keys can only be issued and revoked by users having "Administrator", "Owner" or "API-Administrator" permissions.

 
 

Roles

There are a number of roles that controls what permissions a user has within a specific domain. There are currently five different roles:

  • Owner - This is the user that has the highest responsibility and the e-mail address registered as the customer. The Owner has permissions to do everything such as issue/revoke access keys, create accesses and give users specific roles.
     
  • Administrator - A user that has an "Administrator" role can currently do everything a Owner can, except that Owner has the highest responsibility and is registered as the customer. 
     
  • Installer - An "Installer" is often a temporary role for one or more users installing the Parakey-system. An "Installer" has permissions related to the installation of the product.
     
  • API-Administrator - A user with the "API-Administrator" role can control the domain via the Parakey-API. This role has the following permissions:
     
    • Invite/Remove users
    • Issue/Revoke access keys
    • Read access logs
       
  • Guest - This is the default role of a user, linked to a domain, and does not have any administrative permissions.
 
 

User

A user is identified by its e-mail address and can be linked to multiple domains if the same address is used. A user can have multiple roles and access keys. 

Users are automatically created when an API-request is made to issue an access key to a user (e-mail address) that is not previously registered in any domain. 

An auto generated welcoming e-mail is sent with login information to all new users of Parakey.