Jago API Documentation

Sofia SRL - Copyright © 2017
API Version 1.0 - 2017

Introduction

This Swagger documentation describes how the Jago Access Control Cloud Platform works and how integrations have to be performed from third party developers. If you prefer to work with Postman, you can import the Swagger File into Postman: here a short tutorial. If you need any support about this APIs, please contact us at developers@sofialocks.com.

Baseline concepts

Jago bases its logic on the following main entities:

• Guests: the humans will enter the physical space;
• Locks: the physical smart-lock on doors;
• Credential Rules: the logical elements declaring which guests can enter which locks, specifing also the date and time interval of validity;
• Managers: the humans in charge of managing the physical space.

Each guest and each lock has at least one tag. Each tag is defined by three attributes:

• Name: the tag name
• Category: the tag category
• Color: the visual color used to identify the category

Note. Each lock and each user has as default tag the Guest.username and the Lock.id

Starting as Jago Developer

In order to integrate your existing mobile/web app with our Jago Cloud Access Control Platform, you need to register as Developer and create an App which will be the entity having the authorization of interacting with our backend.

Sandbox and Production Environment

In order to let you to test your integrations, we have a sandbox enviroment you can use to code your integration. This enviroment is a clone of the production one, with the same features and APIs, but it is completely isolated. The two enviroments have two different domains:

• Sandbox environment: sandbox.jago.cloud
• Production enviroment: jago.cloud

Note. Please note that following documentation is referred to the sandbox enviroment.

Developer User Registration

The developer registration has to be performed using the createDeveloper endpoint of our API ecosystem. Such endpoint can be called using curl (as shown below) or thought the Swagger interface we provide.

$ curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "email": "shen.zory@lockturtles.com", "firstname": "Shen", "lastname": "Zory",   "password": "your_dev_user_password" , "licenseCode" : "valid_license_code"}' 'https://api-developers.sandbox.jago.cloud/api/v1/register/developer'

The requested data to register a new developer are:

• email: the developer’s e-mail
• firstname: the developer’s firtname
• lastname: the developer’s lastname
• password: the developer’s account password
• licenseCode: a valid license code. In order to obtain a valid license code, please contact us at developers@sofialocks.com.

If the request succeed, the Jago platform will return you the following payload, where you will get the developer identifier (id) and a confirmation about the data you have inserted.

{
  "id" : 234,
  "firstname" : "Shen",
  "lastname" : "Zory",
  "email" : "shen.zory@lockturtles.com"
}

Developer User Login

Once you have registered as developer, you can perform the login to the cloud platform. For the authentication we use
Grant Type (Resource Owner Password Credentials) as specified by the The OAuth 2.0 Authorization Framework. In order to authenticate, you have to use the following curl command:

$ curl -H "Accept: application/json" https://app:@api-developers.sandbox.jago.cloud/oauth/token -d "grant_type=password&password=your_dev_user_password&username=shen.zory@lockturtles.com"

If the request succeeds, the Jago platform will return you the following payload, where you will get the access_token you have to use to authorize yourself as developer and the refresh_token you have to use to refresh your session. The expires_in represents the number of seconds the token will be still valid. Please note that the role of the user is ROLE_DEVELOPER.

{
  "access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "token_type" : "bearer",
  "refresh_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV...",
  "expires_in" : 172799,
  "scope" : "read write",
  "role" : "ROLE_DEVELOPER",
  "userId" : 234,
  "jti" : "50d5345a-666b-4d37-a623-************"
 }

App creation

As said, in order to integrate your existing software with the platofrm, you have to create an App within our cloud platform. In order to create an app, we suggest you to use the Swagger interface we provide. As first, you have to authenticate yourself (using the access token you got with the steps described in the previous section) within the Swagger interface in order to be able to create an app. Press the Authorize button shown in the picture below.

Once you pressed the Authorize button, the modal window shown below appears; within the value field, insert the access_token you got during the login phase preceded by the bearer string (value == "bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...")

When you filled the value field, press the Authorize button. Now you are authorized within the platform as developer and you gained the power of creating a new app.

The apps have to be managed using the App Controller. In particular, the app creation has to be performed using the createApp endpoint. Such endpoint takes as input the following payload:

{
  "hostName": "lockturtles",
  "name": "Lock Turtles"
}

The hostName is used to craete the custom internet domain for your app. In fact, this field will be used to compose the domain (DNS) to access your access control system backoffice and to expose your APIs. The DNS will be composed as {your_app_host_name}.jago.cloud (or {your_app_host_name}.sandbox.jago.cloud for the sandbox enviroment). In this example, it will be lockturtles.jago.cloud (or lockturtles.sandbox.jago.cloud for the sandbox environment). Such field must contain URL-valid chars. On the other hand, the name field is the name of app you are creating.

Once you have created your app, the Jago platform confirms the operation giving you back the following payload:

{
  "id": 3452,
  "name": "Lock Turtles",
  "appUserId": "d92af5be-f10d-4dab-8a31-************",
  "appUserSecret": "f114704c-cd9b-444d-8952-************",
  "creationDate": 1489572690104
}

The appUserId field is the unique identifier of your app. The appUserSecret is basically the password you have to use when you want to authenticate the app your create to interact with the backend.

Note. Store the appUserSecret in a secure place as soon it is shown by the Jago backend since you will not able to get this value back again. This value will not shown again in the future by any endpoint.

App Login

In order to let your software to interact with our backend, you have to login with the app you have just created. For the authentication of an app, we use
Grant Type (Resource Owner Password Credentials) as specified by the The OAuth 2.0 Authorization Framework. In order to authenticate the app, you have to use the following curl command:

$ curl -H "Accept: application/json" https://client:@api-developers.sandbox.jago.cloud/oauth/token -d "grant_type=password&password={appUserSecret}&username={appUserId}"

In our example,

• appUserId == d92af5be-f10d-4dab-8a31-************
• appUserSecret == f114704c-cd9b-444d-8952-************

If the request succeeds, the Jago platform will return you the following payload, where you will get the access_token you have to use to authorize your app to access the APIs and the refresh_token you have to use to refresh the app session. The expires_in represents the number of seconds the token will be still valid. Please note that the role of the user is ROLE_APP.

{
  "access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6I....",
  "token_type" : "bearer",
  "refresh_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6Ik...",
  "expires_in" : 172799,
  "scope" : "read write",
  "role" : "ROLE_APP",
  "userId" : 5,
  "jti" : "e9ed6d54-7b65-4a96-aad9-************"
}

Now, you have a valid access_token you can use to interact with the Jago platform to create Users, Tags, or CredentialRules. If you want to test how our APIs endpoint interact with the App you have created, we suggest you to use the Swagger interface we provide. As first, you have to authenticate yourself within the Swagger interface in order to be able to create an app. Press the Authorize button shown in the picture below.

Once you pressed the Authorize button, the modal window shown below appears; within the value field, insert the access_token you got during the login phase preceded by the bearer string (value == "bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...")

When you filled the value field, press the Authorize button. Now you are authorized within the platform as developer and you gained the power of creating a new app. Once you have authorized your app, you can do all the operations described in the following sections of this guide.

Everyday operations with Jago

Create a Lock Tag

Before assigning a tag to a lock, it has to be created. The controller to be used is the lock-tag-controller trought the createLockTag endpoint.

The input payload is shown below. The color attribute is the color assigned to the tag you are creating and has to be represented with the Hexadecimal format. The tag has then a name and a type. For instance, if the tag you are creating is going to be assigned to the lock that is the entrance for the Office 101, possible values cloud be "name" == "Office 101" and "type" == "Office"

{
  "color": "#99ff99",
  "name": "Office 101",
  "type": "Office"
}

Create a User Tag

Before assigning a tag to a user, it has to be created. The controller to be used is the user-tag-controller trought the createUserTag endpoint.

The input payload is shown below. The color attribute is the color assigned to the tag you are creating and has to be represented with the Hexadecimal format. The tag has then a name and a type. For instance, if the tag you are creating is going to be assigned to a premium user, possible values cloud be "name" == "Premium Subscription" and "type" == "Subscription"

{
  "color": "#99ff99",
  "name": "Premium Subscription",
  "type": "Subscription"
}

Create a Guest

The creation of a guest has to be performed using the user-controller trought the createUser endpoint. The role attribute has to be set to ROLE_GUEST in order to create a guest. When a new user is created, if the attribute password is not set, an e-mail will be sent to the e-mail address specified within the email field to set the guest account password. Such password has to be used from the guest to login within the mobile app. If the attribute password is set, the password is saved without any e-mail confirmation.

Assign a Tag to a Guest

The assignment of a tag to a a guest has to be performed using the user-controller trought the updateUser endpoint. The userTagIds attribute is an array receiving as input the list of the tag id you want to assign to the selected user.

Assign a Tag to a Lock

The assignment of a tag to a guest has to be performed using the user-controller trought the updateSmartLock endpoint. The lockTagIds attribute is an array receiving as input the list of the tag id you want to assign to the selected lock.

Create a Credential Rule

The creation of a CredentialRule has to be performed using the credential-rule-controller trought the createCredentialRule endpoint. Here some specifications about the data format for some of the attributes of the input payload:

• name: the name of the credentialRule to be created;
• description: the description of the credentialRule to be created;
• guestTagIds: the credentialRule will be applied to all the guests which contains all the tags within this list;
• lockTagIds: the credentialRule will be applied to all the locks which contains all the tags within this list if lockTagMatchingMode == EVERY_TAG or at least one of the tag within the list if lockTagMatchingMode == AT_LEAST_ONE_TAG;
• dateInterval: the date interval you want the guest to enter (from a date to another date) expressed in Unix Time Stamp Epoch Time;
• daysOfTheWeek: the days of the week you want the guest to enter; expressed following the ISO 8601 standard (1 = Monday, 7 = Sunday);
• timeInterval: the time interval within the day to want the guest to enter; it is expressed as the number of seconds from the midnight; for example ((timeInterval.from == 0),(timeInterval.to == 3600)) is equal to ((timeInterval.from == 00:00),(timeInterval.to == 01:00))

Once a CredetialRule is stored, a set of Credentials is generated. The list of the genereted credentials can be retrivied using the getCredentials endpoint. The list of the credentials is updated on the following situations:

• everytime a new credentialRule is created of updated;
• everytime the list of the tags associated to a user or a lock is updated;
• everytime a new guest is craeted.

Create a Manager

The creation of a manager has to be performed using the user-controller trought the createUser endpoint. The role attribute has to be set to ROLE_MANAGER in order to create a manager. When a new user is created, if the attribute password is not set, an e-mail will be sent to the e-mail address specified within the email field to set the manager account password. Such password has to be used from the manager to login within the Jago platform. If the attribute password is set, the password is saved without any e-mail confirmation.

User Login

We use the OAuth2 protocol to manage the authentication to the platform. For the authentication we use
Grant Type (Resource Owner Password Credentials) as specified by the The OAuth 2.0 Authorization Framework. To login within the platform, you have to use the following command.

$ curl -H "Accept: application/json" client:@your_domain.jago.cloud/oauth/token -d "grant_type=password&password=your_password&username=your_username"

As a response, you will obtain an Auth Token you have to use to auhenticate all the calls you are going to perform to the Jago Backend.

Create a Lock

The creation of a lock has to be performed using the smart-lock-controller trought the createSmartLock endpoint. Such endpoint can be used only by users with "role" == "ROLE_INSTALLER".