Skip to main content
BluINFO

BluB0X API Guidance

Overview

BluB0X API Guidance

1.0 Introduction

1.1 Purpose

The purpose of this Guide is to help understand how to implement an automated process which takes information from an external database source and puts it into BluB0X Security’s BluSKY platform using the BluSKY API.  

The intent of this process is to populate BluSKY with information about both employees and non-employees (vendors, contractors, visitors, etc.) from your on-premise Active Directory or other HR server(s).

Optionally, you may wish to also assign Access Rights, apply Application Permissions (Roles), and/or assign Credentials, based on a number of Business Rules as discussed later in the document.

This information will then be used to drive the Physical Access Control System.

For the abbreviated outline of this, please reference Appendix B – Quick Start Guide to Using the BluSKY API

1.2 Definitions, Acronyms, and Abbreviations

Access Right A combination of a specific door/portal and a schedule that specifies when a cardholder can gain access to that door or portal.

Access Level A group of one or more Access Rights that enable a card-holder to gain physical access through the Access Control System.  This Access Level has a name for easy identification.

Access Level Group A group of Access Levels (see above definition of Access Level)

BB BluB0X Security – the manufacturer of BluSKY and the access control system

BS BluSKY – the website that allows authenticated users to manage the security system, monitor hardware, request visitors, etc.

Business RulesLogic that XXX has agreed upon that will either alter the value of fields in BluSKY such that they do not directly reflect their counterpart value in the originating database, or logic that results in a single value in origin database automatically applying additional fields or attributes in BluSKY.

DB IntegrationThe application being developed to feed information from the original data source (Active Directory, Workday, etc.) to BluSKY

PACS, ACS, System – Physical Access Control System or Access Control System for short.

Role A set of permissions within BluSKY that enables the end-user to perform various tasks such as requesting a visitor or administering personnel records.

Source Database The database that data is being read from, such as Active Directory, Workday, etc. in order to send it to BluSKY

Working Database The database that is maintained by the DB Integration to coordinate its efforts between the Source Database and BluSKY

1.3 References

This document pulls its requirements from various sources that have been added as appendices to this document.  

Appendix A – Fields Eligible For Import

Appendix B – Quick Start Guide to Using the BluSKY API

2. Overall Description

The interface being developed (to be referenced as DB Integration) is responsible for identifying information that changes in the source database server, comparing that information to what is already in BluSKY, and updating BluSKY appropriately.  In the process of analyzing that data, various business rules may be applied which would result in applying different Access Levels, Roles, or applying additional capabilities in BluSKY for that record.

All changes initiated by the DB Integration will result in an API call to BluSKY, and these API calls are all logged. 

For development purposes, a lower-level environment will be provided, and the application will need to be certified by BluB0X prior to being given an API license for the Production environment.

Prior to being certified for Production, a detailed analysis of the log file entries for the API will be performed to make sure that:

  1.  The proper API calls are being made with the correct payloads and options
  2.  The API calls are not happening too frequently
  3.  The API calls are not placing undue burden or stress on BluB0X servers.
2.1 Data Structures - Overview

In order to start putting person-related records into BluSKY, several concepts need to be understood and the pre-requisite data structures need to be created.

2.1.1 Required Setup - Systems, Hardware, Companies, and Occupancies

BluSKY organizes data in a manner which is consistent with the real world.  In terms of hardware, everything centers around an Access Control System (ACS), which we often refer to as simply a “System”.

Systems can be created to control access around a single Facility (building) or around multiple Facilities (such as a campus environment).

Companies represent an entire organization (regardless of location), and can have a presence in one or more Facilities by creating an Occupancy for the Company in that Facility.

People are then added to these Occupancies and granted Access Rights to enter various Portals (doors, gates, turnstiles, etc.) within one or more Facilities.  This can be done by assigning Access Levels or Access Level Groups. 

In order to identify themselves when they approach a Portal, people will need Credentials assigned to them.  These can be traditional Prox Cards, Mobile Credentials (which exist solely on a smartphone), biometric scans, or other forms.

Additionally, People can be assigned Permissions to perform various tasks within the BluSKY Application (such as editing personnel records, requesting visitors, running reports, etc).  This is done by assigning Roles to those People.

This document is centered primarily around retrieving, adding, or updating records related to the above-mentioned topics.

For more information on these relationships, please see the documentation in our knowledgebase https://knowledge.blub0x.com/

2.1.2 Optional Setup

There is intrinsic functionality in BluSKY that allows people placed in a company occupancy to automatically be assigned Access Levels and/or Roles (permissions within BluSKY itself) simply because they belong to that occupancy.  This is done by checking off the “Apply by default” option in the Access Level or Role.  This is currently only possible in the UI of BluSKY, but will be added to the API in future versions.

Some examples of how automatically-applied Access Levels could be applied:

  • Create one Access Level for Employees called “Global Access” with general access to all Facilities across the glob
    • Apply this by default to all people added to your company and then programmatically ADD any necessary additional Access Levels for each individual based on their individual needs/business rules (such as “all executives get the “Executive wing access level”).
  • Create one Access Level for Consultants in each building, that contains only general access to a single building – each consultant will then have access only to the facility that contracted them.
  • Create two Role
    • Employee – will contain all necessary permission plus visitor admission permissions
    • Consultant – will contain no permissions other than requesting visitors.

3. Application Logic

3.1 Initialization Sequence

Upon startup, the application will read its initial settings from its configuration file. The key bits of information that it will need are:

  • Connection string for the BluSKY WebAPI – this will differ between QA and Production environments
  • Credentials for the BluSKY WebAPI (encrypted)
  • Connection string for the Source Database server – this may differ between QA and Production environments within your infrastructure
  • Credentials for the Source Database, such as Active Directory, Workday, etc. (encrypted)
  • Connection information for an application-specific database (Working Database) that helps enforce business rules and sync logic (note that this is a “working” database for the application, not necessarily on the same server as the personnel source database (AD, Workday, etc) – this will differ between QA and Production environments
  • Connection information (path and credentials) for a photo repository folder with encryption as necessary.
  • Frequency of sync’ing process – anything from “every 20 minutes” to “once a day at midnight” – this should be driven by business needs.
  • EmployeeBadgeTemplateId(s)
  • ConsultantBadgeTemplateId(s)
  • Notification email string – a delimited string of valid email addresses to send error notifications to (on your side)
3.1.1 Occasional Query – Once a Day

There are a few reference tables in which the DB Interface may need to reference and keep updated via infrequent calls to BluSKY.  This includes keeping mapping tables for the Source Database’s locations/workplaces to the corresponding Systems, Facilities, and Occupancies in BluSKY. 

Note 1:  If you are only dealing with a single occupancy that all of your people will be going into, then you can simply set the ACSystemId, FacilityId, and OccupancyId in your configuration file and bypass the first three API calls listed below.

Note 2:  If you are not going to be adding Access Rights via the API, or are relying on automatically-assigned Access Levels only, then you can skip Access Levels and Access Level Groups below.

Note 3: If you are not going to be adding Roles via the API, or are relying on automatically-assigned Roles only, then you can skip the Roles item below.

Note 4: If you are not going to be adding Credentials (Cards) via the API then you can skip the Card Types item below.

In order to do this, the DB Interface Application will need to call the following methods once-a-day, or at most, once-an-hour:

  1. Conditional: To get a list of Systems from BluSKY: Issue a GET call to https://qaapi.blub0x.com/api/v1/ACSystems (for development) or https://api.blub0x.com/api/v1/ACSystems (for Production)
  2. Conditional: To get a list of Facilities:  Issue a GET call to https://qaapi.blub0x.com/api/v1/Facilities (for development) or https://api.blub0x.com/api/v1/Facilities (for Production)
  3. Conditional: To get a list of Occupancies: Issue a GET call to https://qaapi.blub0x.com/api/v1/Occupancies?IncludeDeleted=false (for development) or https://api.blub0x.com/api/v1/Occupancies?IncludeDeleted=false  (for Production)
  4. Optional: To get a list of AccessLevels: Issue a GET call to https://qaapi.blub0x.com/api/v1/AccessLevels (for development) or https://api.blub0x.com/api/v1/AccessLevels  (for Production)
  5. Optional: To get a list of AccessLevelGroups: Issue a GET call to https://qaapi.blub0x.com/api/v1/AccessLevelGroups (for development) or https://api.blub0x.com/api/v1/AccessLevelGroups  (for Production)
  6. Optional: To get a list of Roles: Issue a GET call to https://qaapi.blub0x.com/api/v1/Roles (for development) or https://api.blub0x.com/api/v1/Roles  (for Production)
  7. Optional: To get a list of Card Types: Issue a GET call to https://qaapi.blub0x.com/api/v1/CardTypes (for development) or https://api.blub0x.com/api/v1/CardTypes  (for Production)

Once each of the above calls is completed, their data should be placed in the working table for the DB Integration (Working Database) for reference in future API calls that require Primary Key identifiers from BluSKY.  Some care should be taken as you may have additional columns you wish to store (such as the Primary Key identifiers from the Source Database), thus you don’t want to necessarily purge and repopulate the Working Database tables, but rather do an intelligent Update operation to it.

3.2 Running Logic
3.2.1 Overview

Based upon the frequency in the configuration information, similar logic to the following should run every x minutes (as configured):

DB Interface will read from its “working” database the last time that it ran.  This will be used to determine which rows might have changed in the Source Database since the last execution.

The DB Interface main function will connect to the Source Database server (using configuration information) and query for all rows whose “last changed date” value exceeds the last time the DB Interface ran (as retrieved above).

For all rows whose “last changed” value exceeds the last-ran value:

---------------------------------

Look in the Working Database and see if there is a row with the same EmployeeID field (or other unique identifier that is designated).

If there is NOT a matching Working Database field, then this is a new record:

  • Generate a hash of all the fields listed in Appendix B
  • Create a new row in the Working Database with the EmployeeID, the hash value, ManuallyDeletedDateTime = null, and the current datetime
  • Call the BluSKY WebAPI to add this person (see section 3.2.2 Adding A Person Via WebAPI)
  • Take the returned User Id from the API call and add it to your Working Database table to map the original EmployeeId/Unique Identifier to the BluSKY Primary Key

If there is already a matching Working Database field, then this is an existing record and we might need to update it. 

  • Generate a hash of all columns in the Source Database record that are contained in Appendix B
  • If the generated hash is different than the hash stored in the Working Database AND
    ManuallyDeletedDateTime is null, then:
    • Update the hash in the Working Database to new hash value
    • Follow procedures in 3.2.3 Updating A Person Via WebAPI

After running through all existing rows in Source Database, the DB Integration Application will compare all rows that currently exist in the Working Database with hash codes and see if there are still rows in the Source Database that match the employee id for that row in the Working Database.  If there is not a corresponding row in Source Database, then this will count as a terminated employee and the DB Integration shall remove this row from the Working Database and update the personnel record in BluSKY with an EndDateTime = now – 1 day and/or Delete the record (as determined by business policy.)

3.2.2  Adding A Person Via WebAPI

If you have more than one office location/Occupancy that you are dealing with - Start by looking at the Source Database field which indicates where the person works and find the corresponding ACSystemId, FacilityId, and OccupancyId values from your Working Database that helps map these items.

If there is a value not contained in your mapping table, then ignore this row and send an error to your application development team indicating that there are unmapped work locations.

Next, look at the EmployeeId field (or another unique identifier) to determine that this record can be uniquely identified.  If the value is not unique then ignore this row and send an error to your application development team indicating that there are missing unique identifiers for this person.

We should now be able to add the person:

AddUser method of API: https://knowledge.blub0x.com/Web_API/Person/AddUser

  • FirstName = GivenName (Source Database)
  • LastName = Surname (Source Database)
  • MiddleInitial = Middle Initial (Source Database)
  • sGenderId = 1 = Male, 2 = Female, 3 (Unspecified Gender)
  • DefaultFloorId = xxx
  • DefaultFloorStopId = xxx
  • FacilityId = FacilityId for the Facility that matches in the Working Database’s mapping table
  • CompanyInstanceType = 1 (Occupancy)
  • CompanyInstanceId = OccupantId for the Occupancy that matches in the Working Database’s mapping table
  • ACSystemId = ACSystemId for the System that matches in the Working Database’s mapping table
  • StartDateTime = Employment Start Date (Source Database) or null.  If populated, the person’s access will not become valid until AFTER this value.
  • EndDateTime = Employment End Date (Source Database) or null.  If populated, the person’s access will not be valid AFTER this value.
  • AccessRightsSuspended (bool) = False if Source Database indicates this record is active
  • AccessRightsSuspendedStart = null if Source Database indicates this record is active, If “Enabled” = false, then now – 1 day
  • AccessRightsSuspendedEnd = null
  • WebSiteRightsSuspended (bool) = False if Source Database indicates this record is active WebSiteRightsSuspendedStart = null if Source Database indicates this record is active, If “Enabled” = false, then now – 1 day
  • WebsiteRightsSuspendedEnd = null
  • BadgeTemplateId = EmployeeBadgeTemplateId or ConsultantBadgeTemplateId from configuration settings based appropriate business logic
  • Employee Number = Employee Number from Source Database
  • HasLoginRights = True for anyone that needs to login to BluSKY to administer or if they will need to request visitors, etc.
  • Job Title = Title from Source Database
  • Photo = To be handled in another thread.  See 3.3 Photo Population
  • Deleted = false unless you are adding inactive people from the Source Database (Terminated Employee)

This method returns the PersonId that was assigned by the database to the Person that was just created.  Optionally, you can pass the PersonId as a parameter to the above function.

Once the record is created via the WebAPI, BluSKY will automatically apply any appropriate Access Levels and Roles depending on which Occupancy they were placed in (based on Apply-By-Default attributes of those ALs and Roles).

If additional Access Levels are required based on other business logic (such as department or other fields in the Source Database), then please refer to section 3.2.4 Adding Access Levels.

If additional Roles are required based on other business logic (such as department or other fields in the Source Database), then please refer to section 3.2.5 Adding Roles.

AddUserContactItem: https://knowledge.blub0x.com/Web_API/Person/AddUserContactItem

This will be called twice. Once for the email address:

  • UserId = Person Object PersonId as returned from the AddUser method
  • ContactType = WorkEmail
  • Value = Primary work email address from Source Database
  • IsDefault = true

Once for the Phone Number

  • UserId = Person Object PersonId as returned from the AddUser method
  • ContactType = WorkPhone
  • Value = Office Phone from Source Database
  • IsDefault = true

For the add methods, the Person Audit tables will automatically be populated with appropriate information.

3.2.3  Updating A Person Via WebAPI

If you have more than one office location/Occupancy that you are dealing with - Start by looking at the Source Database field which indicates where the person works and find the corresponding ACSystemId, FacilityId, and OccupancyId values from your Working Database that helps map these items.

If there is a value not contained in your mapping table, then ignore this row and send an error to your application development team indicating that there are unmapped work locations.

This will determine which building and occupancy the record will need to be in.  If this differs, we will have to “move” the record from one occupancy to another.

If the OccupancyId value has changed:

Next, look at the EmployeeId field (or other unique identifier) to determine that this record can be uniquely identified.  If the value is not unique then ignore this row and send an error to your application development team indicating that there are missing unique identifiers for this person.

We should now be able to update the person:

UpdateUser method of API: https://knowledge.blub0x.com/Web_API/Person/UpdateUser

  • FirstName = GivenName (Source Database)
  • LastName = Surname (Source Database)
  • MiddleInitial = Middle Initial (Source Database)
  • sGenderId = 1 = Male, 2 = Female, 3 (Unspecified Gender)
  • DefaultFloorId = xxx
  • DefaultFloorStopId = xxx
  • FacilityId = FacilityId for the Facility that matches in the Working Database’s mapping table
  • CompanyInstanceType = 1 (Occupancy)
  • CompanyInstanceId = OccupantId for the Occupancy that matches in the Working Database’s mapping table
  • ACSystemId = ACSystemId for the System that matches in the Working Database’s mapping table
  • StartDateTime = Employment Start Date (Source Database) or null.  If populated, the person’s access will not become valid until AFTER this value.
  • EndDateTime = Employment End Date (Source Database) or null.  If populated, the person’s access will not be valid AFTER this value.
  • AccessRightsSuspended (bool) = False if Source Database indicates this record is active
  • AccessRightsSuspendedStart = null if Source Database indicates this record is active, If “Enabled” = false, then now – 1 day
  • AccessRightsSuspendedEnd = null
  • WebSiteRightsSuspended (bool) = False if Source Database indicates this record is active WebSiteRightsSuspendedStart = null if Source Database indicates this record is active, If “Enabled” = false, then now – 1 day
  • WebsiteRightsSuspendedEnd = null
  • BadgeTemplateId = EmployeeBadgeTemplateId or ConsultantBadgeTemplateId from configuration settings based appropriate business logic
  • Employee Number = Employee Number from Source Database
  • HasLoginRights = True for anyone that needs to login to BluSKY to administer or if they will need to request visitors, etc.
  • Job Title = Title from Source Database
  • Photo = To be handled in another thread.  See 3.3 Photo Population
  • Deleted = false unless you are adding inactive people from the Source Database (Terminated Employee)

If either of the contact fields changes (OfficePhone or UserPrincipalName), then we will need to remove that contact item from the user first by calling RemoveUserContactItem (https://knowledge.blub0x.com/Web_API/Person/RemoveUserContactItem) and then re-adding it with the correct information:

AddUserContactItem: https://knowledge.blub0x.com/Web_API/Person/AddUserContactItem

This will be called twice.  Once for the email address:

  • UserId = Person Object PersonId as returned from the AddUser method
  • ContactType = WorkEmail
  • Value = Primary work email address from Source Database
  • IsDefault = true

Once for the Phone Number

  • UserId = Person Object PersonId as returned from the AddUser method
  • ContactType = WorkPhone
  • Value = Office Phone from Source Database
  • IsDefault = true
3.2.4 Adding Access Levels

In order to explicitly add a specific Access Level to a person, you need to call the Add Access Level method:

https://qaapi.blub0x.com/api/v1/Users/{User_ID}/AccessLevels (For lower environment) or https://api.blub0x.com/api/v1/Users/{User_ID}/AccessLevels (For Production)

The arguments to this method are the PersonId returned from Adding or Updating a User record and an Access Level Id that was retrieved and mapped in the Working Database as outlined in Section 3.1.1 (Occasional Query) above.

3.2.5 Adding Roles

In order to explicitly add a specific Role to a person, you need to call the Add Role method: https://qaapi.blub0x.com/api/v1/Users/{User_ID}/UserRoles  (For lower environment) or https://api.blub0x.com/api/v1/Users/{User_ID}/UserRoles  (For Production)

The arguments to this method are the PersonId returned from Adding or Updating a User record and a RoleId that was retrieved and mapped in the Working Database as outlined in Section 3.1.1 (Occasional Query) above.

3.2.6 Adding Credentials to a User

Many DB Integrations rely on credentials to be added outside of the Source Database, meaning that credentials are added and managed directly in BluSKY.  However, if the Source Database does track credential information, then they can be added via the BluSKY API.

Prox Cards:

In order to add a specific Credential (Prox Card) to a person, you need to call the Add Card method: https://qaapi.blub0x.com/api/v1/Users/{User_ID}/UserCards  (For lower environment) or https://api.blub0x.com/api/v1/Users/{User_ID}/UserCards  (For Production)

The arguments to this method are:

ReassignCardIfAlreadyAssigned - Optional. If true, deletes current card assignment (if any) for a given card before assigning it to the given User (boolean)

UserId - Required: The PK of the existing User that you want to add the card to as returned by the Add method or as retrieved from the mapping table in Working Database (globally unique identifier)

CardId - Optional: The PK of an existing card that you want to assign to the User. Retrieve possible values from mapping table in Working Database. If null, CardType, CardACSystem, InternalCardNumber, ExternalCardNumber and Facility code are required. (globally unique identifier)

CardType - Conditional: If CardId is null, this is required. Represents the type of card being added dynamically. Retrieve possible values from /Card/GetAllCardTypes (integer)

CardACSystemId - Conditional: If CardId is null, this is required. Represents the Access Control System of the card being added dynamically. Retrieve possible values from /ACSystem/GetAllSystems (globally unique identifier)

InternalCardNumber - Conditional: If CardId is null, this is required. Represents the internal/encoded number of the card being added dynamically. (integer              )

ExternalCardNumber - Conditional: If CardId is null, this is required. Represents the external number printed on the card being added dynamically. (string)

CardSerialNumber - Conditional: If CardType supports it, this is required. Represents the serial number of the smart card being added dynamically. (integer)

FacilityCode - Conditional: If CardType supports it, this is required. Represents the facility code of the smart card being added dynamically. (integer)

IssueCode - Conditional: If CardType supports it, this is required. Represents the issue code of the smart card being added dynamically. (integer)

PIN - Optional: The PIN that the User may use in conjunction with this Card for Card + PIN mode or for when Readers are in PIN mode only. (string)

EnforceOccupancySystem - Optional: Requests to verify if the CardACSystemId matches the system the User's Occupancy belongs to (Boolean)

CardActivationStartDateTime - Optional: Date and time of the card activation (date)

CardDeactivationStartDateTime - Optional: Date and time of the card de-activation (date)

CardUserFlags - Card User Flags with a minimum value of 1 to be considered active as defined by: https://api.blub0x.com/Help/ResourceModel?modelName=CardUserFlags

3.3 Photo Logic

All photos will be stored by XXX as [EmployeeID].jpg.

A separate process will run after each AD sync (every 20 minutes) looking for photos that have been added or updated.  This thread will look in the directory that is configured in the configuration settings and pass any credentials necessary to gain programmatic access to the folder. 

Once access has been granted, DB Integration Application will read from the Working Database the last time that it ran a photo check.  This will be used to determine which photos have changed since last run.  If this value is null (first time running), then DateTime.Minimum will be used, essentially indicating that all photos have changed.

The DB Integration Application’s photo function will query for all photos whose date created or date modified value exceeds the last time the photo check ran.

For all applicable photos, the DB Integration Application will:

  • Resize the image to appropriate sizes to minimize load times in the browser
  • Upload the resized image from the photo fileshare to BluSKY:
  • Call WebAPI method called AddUserPhoto: https://qaapi.blub0x.com/api/v1/Users/Photo (for lower environment) or https://api.blub0x.com/api/v1/Users/Photo (for Production)
    • NOTE: The ImageData has to be base64-encoded
    • The PersonId = the PersonId that corresponds to the value returned from AddPerson.
    • ImageData (collection of bytes in base-64 encoding)
    • FileName desired – can just use PersonId if you wish
    • ThumbFileName - thumbnail file name must be different from the FileName
    • SetAsDefault = true
3.4 Error Handling

All errors must be handled.  Best effort must be made to react appropriately to an error. If the error is a transient condition, such as not being able to connect to a server, then the error should be handled by logging and retrying.

There should be an overall error handling block that catches unhandled exceptions so that the service does not crash.

Unhandled exceptions should also be reported to the development team to address.

For “handled” exceptions, the DB Integration Application should have configuration settings to figure out who needs to be notified via email.

Appendix A:  Fields available for AD Import

Person-Related Fields

 

 

Field Name

DataType

Nullable?

Person Type

string

Nullable

Company Name

string

NON-Null

First Name

string

NON-Null

Last Name

string

NON-Null

Middle Init

string

Nullable

Floor

string

Nullable

Job Title

string

Nullable

Gender

string

Nullable

Employee Number

string

NON-Null

Person Start DateTime

DateTime

Nullable

Person End DateTime

DateTime

Nullable

Primary Email Address

string

NON-Null

Secondary Email Address

string

Nullable

Phone 1

string

Nullable

Phone 2

string

Nullable

Phone 3

string

Nullable

BluB0X Login Rights

boolean

Nullable

Photo

file

Nullable

     

Badge Related Info:

   

Badge Template

string

Nullable

     

Role Related Info:

   

Rolename1

string

Nullable

Rolename2

string

Nullable

     

Card-Related Info:

   

Allow One Free Antipassback Pass

boolean

Nullable

Antipassback Exempt

boolean

Nullable

Use ADA Timing Paramaters

boolean

Nullable

VIP

boolean

Nullable

Vertigo

boolean

Nullable

Fire Warden

boolean

Nullable

     

Access Related Info:

   

Access Level Name 1

string

Nullable

Access Level Name 2

string

Nullable

Access Level Name 3

string

Nullable

     

User Defined Fields:

   

TBD

Any

Flexible

TBD

Any

Flexible

Appendix B: Quick Start Guide to Using the BluSKY API

1.  Familiarize yourself with the API functionality using the help page (https://qaapi.blub0x.com/help for QA env.) and decide which features to use for your integration with Blub0x

2.  Obtain QA authentication credentials from Blub0x or the integrator

3.  Decide on the tool to use for development and debugging. Blub0x recommends Postman (https://www.getpostman.com/downloads/

4. Issue a POST request to https://qaapi.blub0x.com/token supplying user ID and password from step #2 as body:

Screen Shot 2021-10-18 at 7.32.25 PM.png

  • Switch to Body tab, select “x-www-form-urlencoded” and put in the following keys and values:

Screen Shot 2021-10-18 at 7.34.36 PM.png

  • Click “Send” button

Successful response would contain the authentication token required for all API calls:

{ "access_token": "Z14uzjHSNQfZsWkxJbZN9oh7bdasmuqNRKO8rOx9nmsQu3PkpF_I-ii07m1f5VqHHbO-6fCJLBpO3ac27_zkXjgVYTX1ouec573U032Wt2QOViN3JhGah91i3-d5U3HkgH8FUB_OFYR62moD4uc301YZGtXEGiS1GRpu7Xylga-k2jdUJEVc6FIBpF0aHbqTCDWBd8psihuxDXRBP_Y8qCzuTsRaYVcYtssfNARrmZv63ObENQZ9aEGdiEPwsrRQmKzkz4zWcu0F4ll0Qhxv8M1DVxqmrdpGbn3Q2bqocQJfZh5hTosd1eK9A54DViV7718DL0XCArx27k-CmWDzG4S15jYLY8hxQS1UcF8l4CCh112bwVEI2bem_AUU7LN4zVCuu4Mxankjrp9L4-z-g0R9UXulhcCIlQji67x1MWt_vKSa6leKRljywhZ6Ojgot1lHQJWfr2KnM8XKnLPUMNlxtw1qM8cbPR5WIxCWGw_TIoIQ",  "token_type": "bearer", "expires_in": 1209599, "userName": "xxxxxxxxxxxxx", ".issued": "Fri, 17 Aug 2019 01:16:48 GMT", ".expires": "Fri, 24 Aug 2019 01:16:48 GMT" }

5. Now you can start issuing API calls against the QA instance of the API (https://qaapi.blub0x.com) supplying the following HTTPS headers (see examples below):

Content-Type:application/json; charset=utf-8

Authorization:Bearer

Z11uzjHSNQfZsWkxJbZN9oh7bdasmuqNRKO8rOx9nmsQu3PkpF_I-ii07m1f5VqHHbO-6fCJLBpO3ac27_zkXjgVYTX1ouec573U032Wt2QOViN3JhGah91i3-d5U3HkgH8FUB_OFYR62moD4uc301YZGtXEGiS1GRpu7Xylga-k2jdUJEVc6FIBpF0aHbqTCDWBd8psihuxDXRBP_Y8qCzuTsRaYVcYtssfNARrmZv63ObENQZ9aEGdiEPwsrRQmKzkz4zWcu0F4ll0Qhxv8M1DVxqmrdpGbn3Q2bqocQJfZh5hTosd1eK9A54DViV7718DL0XCArx27k-CmWDzG4S15jYLx8hxQS1UcF8l4CCh112bwVEI2bem_AUU7LN4zVCuu4Mxankjrp9L4-z-g0R9UXulhcCIlQji67x1MWt_vKSa6leKRljywhZ6Ojgot1lHQJWfr2KnM8XKnLPUMNlxtw1qM8cbPR5WIxCWGw_TIoIQ

6. The first call you’re likely to make is to obtain the SystemID. To do this you need to issue a GET call to https://qaapi.blub0x.com/api/v1/ACSystems

  • Put the following keys and values on the Headers tab (put in the “Bearer” word as an Authorization value and copy the authorization token body from the previous step):

Screen Shot 2021-10-18 at 7.36.35 PM.png

  • Click “Send” button
  • The response should look like this:
{  "ACSystemId":   "c4d6de54–8842–4bfe–8d52–26cdf4fdaf56  ", "Name":   "Your System", "Deleted":   false, "CustomerID":   "19fc3978-685b-4b0b-a211-b9d8ae79e518  ", "CustomerName":   "Your Company", "IntegratorId":   "fc9f6b9d–9594–400b–a4d3–0ab5c450d514      ", "IntegratorName":  "Your Integrator"  }

7.  Now you need building(s) of the given system (https://qaapi.blub0x.com/api/v1/Facilities)

8.  Retrieve the existing occupancy or create a new one

i.  Refer to https://api.blub0x.com/Help/Api/POST-api-v1-Occupancies for details

9. Use your Occupancy ID to add people: https://qaapi.blub0x.com/api/v1/Users

i.  The ImageData has to be base64-encoded

ii.  The thumbnail file name must be different from the FileName

i.  Note: you will need to retrieve existing roles first to get the RoleID for the above call: https://qaapi.blub0x.com/api/v1/Roles

  • Add Access Levels and/or Access Level Groups:

i.   Add Access Level: https://qaapi.blub0x.com/api/v1/Users/{User_ID}/AccessLevels

ii.  Add Access Level Group: https://qaapi.blub0x.com/api/v1/Users/{User_ID}/AccessLevelGroups

10.  Once the application is complete submit it to Blub0x for validation

11.  Obtain PROD credentials from Blub0x

12.  Point your application to the PROD instance of the API (https://api.blub0x.com)

 

  • Was this article helpful?