Note

Make sure you have gone through the  Spintly Integration Overview section, as that section will help you understanding the spintly platform and the types of integration, This  integration can be combined with type 5 integration

Use Case for Integration

This integration is normally used when a client just want to use Spintly access management service, how this is different from type 2 integration is in type 2 spintly apart from access management, also gives other modules like user management, visitor management, attendance management, and all its ui capabilities, In type 3 integration, the client gets apis only of the access management section.

Live example:

This solution is already live and implemented by lot of our Indian customers namely Godrej, So here the client had thier own website and app, with this integration the client included the spintly sdk in thier app, so with this app the client could open the doors, they also integrated spintly backend with thier own software, whenever a user is added or permissions were changed, spintly apis were called to create accessor and update the permissions and the same permission would reflect in the app via the sdk

The features to be offered in this integration

Entities involved in this integration

As you can see in the below diagram, for type 3 integration to work the following entities will be needed, below are the entities needed

1. Spintly Cloud: here different apis will be exposed which the client can use
2. Client Cloud: here the backend of the client will be hosted this backend will be reponsible for talking to the spintly cloud as well as client mobile app
3. Spintly SDK: Here the  spintly access sdk will be given to the client, client must include the sdk in its app, the SDK will be exposing different
   functions which the client app can use to access the doors
4. Client app: This will be front facing app for the customer, apart from access client will be exposing different services to the client
5. Spintly Reader: Once the user is logged in the client app, he can tap on the reader and open the door

Steps to get up and running

Please refer the following link to get up and running along with type 6 integration

please refer the following link to get up and running without any other integration

Examplexample of how you can integrate type3 with your application 

Mobile SDK

Please refer the following link to know in depth how to integrate the  spintly access sdk

Following are the apis 

1. Oauth apis
2. Get all sites
3. Get access points of a site
4. Create accessor
5. Get accessor permissions
6. Update accessor permissions
7. Get access point  permissions
8. Update access point permissions
9. Assign Credential
10. Unassign Credential
11. Delete accessor

1) Ouath Api

Spintly uses oauth 2.0 client credential flow for authorization purpose, here in the api the client just has to put a clientid and clientSecret to get an access token, this access token can then be used to access other apis of Spintly.

2) Get Sites

This api is responsible for getting all the sites belonging to the Integrator, As you can see in the diagram

3) Get Access points

This api is responsible for getting all the access points(doors), that belong to a particular site

4) Create Accessor

This api is responsible for creating an accessor(user), while creating the accessor, you will need to provide the organisation, you can also specify the permissions while creating the user(not mandatory, you can give permissions after creating the accessor also, you can check below few apis for the same), while giving permissions you can mention what kind of modes of permission the accessor can get ie mobile, card,fingerprint or face, in mobile there are more modes namely tap to access, click to access remote access etc, if Mobile access is given then the identity info needs to be present ie providerid(this will be provided by spintly) and sub(this is unique identifier which will be present in the  jwt token which will be passed to the mobile access sdk). When the accessor is created it will give you an accessorid in the response which needs to be mapped to the userid in you software/backend

Modes Of access

Modes of Mobile Access

Request Body

Response

5) Get accessor permissions

This api is responsible for for getting all the access point permissions of the accessor

6) Update accessor permissions

This api is responsible for  updating the accessor permissions, in the permissionsToAdd you can specify what access point permission to give. Here the request body is similar to create accessor. In the permissionstoRemove you can specify the permissions to be removed.  Please note you cannot add and remove the same access point permissions at the same time. The below combinations are allowed. 

1. Updating only permissionsToAdd

2) Updating only permissionsToRemove

3) Updating both permissionsToAdd and permissionsToRemove

7) Get access point permissions

This api is responsible for for getting all the accessor  which has permissions to a partiicular access point

8) Update access point permissions

This api is responsible for updating all the accessors  on a particular access point. Please note this api may look similar to update accessor permissions api, only difference is there for particular access you can give different access point permissions, whereas in this api for a particular access point you can give permissions to different accessors. Please note you cannot add and remove the same access point permissions at the same time. Like update accessor permissions api, here also different combintation are allowed:

2) Updating only permissionToRemove

3) Updating both permissionsToAdd and permissionsToRemove

9) Assign Card Api

This api is responsible for assigning a card to an accessor

10) Unassign Card Api

This api is responsible for unassigning a card of an  accessor

11) Delete Accesor Api

This api is responsible for deleting an acccesor

12 User Schedule

12a) Create Schedule

This api is responsible for creating user schedule, Steps how to get user schedule working are as followed

1. You need to first create a schedule
2. Create an accessor and assign the accessor permissions
3. Assign the user schedule

 The request body of create schedule has the following

name: When creating a schedule, please make sure a meaningful name is given

sections: Here in this section you can specify  what will be settings of the schedule for each day of the week

repeatType: In sections, there will be field called as repeatType, it has two value ie once or weekly, once means if the schedule needs to be triggered once only, if it once you need specify the date when it will get triggered. weekly means the schedule will get always triggered every week

daysOfWeek: In section, there will be field called as daysOfWeek. Here you need to specify the days in integer format, below are the values

Triggers: In section, there will be a field called as triggers, triggers basically tell which time section the door should deny access to the user and when the door should grant access to the user, it has two fields ie state and time, The time field you can either specify in minutes or in hours and below are the values  for the same

Once a schedule is created it will give a scheduleId and  different sectionId. When creating a schedule it is mandatory to put the holiday section also(ie christmas 25th December, new years 1st January), the holiday section will always overwrite the existing schedule

Please check the below section how you can use the above in an api

a) Creating a user schedule from 9am to 6pm for the all the days of the week (Case 1) and also specifying the holidays also (25th dec)

Below is how the requestBody will look like, here the triggeres section states that from 00:00 to 9:00 the user will be getting access denied, from 9:00 to 17:00 the access will be enabled for the user and from 17:00 to 23:59 the user will be getting access denied

a) Creating a user schedule from 9am to 5pm for Monday, and 6am to 1pm for the other days (Case 2)

Below is how the requestBody will look like, as you can see there are 2 entries in the sections, on  entry has the setting only for monday schedule, where as the second section has settings for Tuesday,Wednesday, Thusrday, Friday and Saturday. Here  mondays trigger section states that from 00:00 to 9:00 the user will be getting access denied, from 9:00 to 17:00 the access will be enabled for the user and from 17:00 to 23:59 the user will be getting access denied. Whereas for the rest of the week the second section states that from 00:00 to 06:00  the user will be getting access denied, from 06:00 to 13:00 the access will be enabled for the user and from 13:00 to 23:59 the user will be getting access denied. 

As you can see above each week of a day can have its own schedule, it all depends on a companies use, some company may want to have the same schedule for all the days of the week, some companies may want to have different schedule for all different days of the week. Basically there can be different permutation and combination of the schedules. but whenever a schedule is created all the days of the week need to be specified, otherwise schedules cannot be created

When a schedule is created, the api will always give a schdeuleid and sectionids(depending on how many schedules are created), below are the response for the above two cases

Case1 response

Basically it will return you the same thing what you had mentioned in the requetbody, only for few things, it will  return a scheduleId(highlighted in blue) and sectionId(highlighted in red), this values are important, as using the ids you can update or delete the schedule accordingly

Case2 response

It will return a response identitcal to case1, but  since in case 2 there were different sections, it will return you two section ids, for explanation sake , the response has been minimized, here the red arrow indicates section 1 id (ie of mondays) and orange arrow indicates section 2 id (ie of Tuesdays, Wednesdays, thursdays, Fridays and aturdays)

12b) Getting all the user schedules of an organisations

This api is responsible for getting all the schedule for the organisaitons

12c) Getting details of a particular schedule in depth

This api is responsible for getting details of a particular schedule

12d) Updating an existing schedule

This api is responsible for getting updating existing schedules, here lets try to update the schedule already created in the create schedule section,  pleas refer case1 and case 2 of create schedule for more context

case 1 updating

Say you wan to update the end tie for case 1 from 17:00 to 19:00, then the reuqest body will look like below, as you can see below the scheduleId(marked as organe) in the url is the same id which we got while creating the first schedule. In the request body there is a field called as update, the update is nothing but the sectionid which you need to update,

case 2 updating 

Case 2 updating is the same as case 1 updating, only different is, in case 2 there were 2 sections created, you can either update both the sections o update only one section

updating 2 sections on an existing schedules, as you can see you need to specify both the section ids(red and orange) if you want to update both

12e) Deleting an existing schedule

This api is responsible for deleting an  existing schedules, as you can see you just need to specify the orgid and scheduleid

12f) Assigning schedule to an accessor

This api is responsible for assigning a schedule to an accessor, here you can specify which alll accessors needs to given the schedule, also it needs to tell which access point the schedule needs to be applied. Multiple schedules cannot be assigned on the same door as of now

12g) Unassigning schedule to an accessor

This api is responsible for unassigning a schedule to an accessor, here you can specify which alll schedules needs to be removed from an accessor

12i) Get the schedules assigned to a user (accessor filter)

This api is responsible for getting all permissions of an accessor and showing which all access points has schedule assigned and which all access point has schedule unassigned

12i) Get the schedules assigned  to a user (access point filter)

This api is responsible for getting all permissions of an access point and showing which all access points has schedule assigned and which all access point has schedule unassigned