Mobile API User Guide
- Vinodhraj DP
- 1 About This Guide
- 2 Getting Started
- 3 Register/Login
- 4 Login Using Access Token
- 5 Renew Access Token
- 6 Deregister Mobile Device
- 7 Change User Password
- 8 Access Using Geolocation Data
- 9 Update Beacon Status
- 10 Beacons
- 11 Controlled Areas
- 12 Access Groups
- 13 Update Controlled Area State
- 14 Momentary Unlock Controlled Area
- 15 Create Controlled Area Schedule
- 16 Controlled Areas By Access Group
- 17 Schedules
- 18 GLOSSARY
About This Guide
This guide describes how to configure and use the PRIMIS MOBILE API software.
Topics in this guide are intended for security system integrators and security administrators responsible for setting up IP-based physical access security control systems.
Additional Documentation
To find documentation available for all products, go to https://www.identiv.com/primis
Getting Started
Introduction
The Primis Mobile API provides the RESTful Web Services for the Primis Access Control System. Depending on the operation, the Primis Mobile API calls required HTTP basic authentication using the email and the password of the mobile user or HTTP bearer authentication using JSON Web Token (JWT).
The Primis Mobile API Web Services must be configured to use https. Please contact support for additional details.
Register/Login
This chapter describes how to register a new mobile device to Primis or login to Primis using the email and password of the mobile user.
Request Header:
Method | URI | Authorization | Comments |
POST | /api/mobile/login | Basic authentication | Basic authentication using the email and password of the mobile user. |
Request Body:
JSON Property Name | Type | Description | Comments |
phoneId | String | Unique identifier for the mobile device | The phoneId is assigned by the mobile application. |
Response Body:
JSON Property Name | Type | Description | Comments |
|---|---|---|---|
registered | Boolean | Always return true |
|
isAdmin | Boolean | Indicate whether the user is a Primis administrator |
|
String | Email address of the user |
| |
beacon | JSON Object | Beacon configuration in Primis |
|
jwt | String | Access token | Access token for accessing the Primis Mobile API. |
phone-id | String | Unique identifier for the mobile device |
|
status | String | Result status of the operation | “ok” if the operation is successful |
zoneAccess | Number | User access privilege on controlled area configuration | 0 – no access to controlled area configuration |
refreshToken | String | Refresh token for renewing the Access Token |
|
Register a new mobile device
POST /api/mobile/login
https://<ip address>:<api listening port>/api/mobile/login
Content-Type: application/json
Post Data:
{"phoneId": "9F58395D-7963-469C-BB8F-5C39A31B2B6Z"}
Response Data:
{
"registered":true,
"isAdmin":true,
"email":"john.smith@identiv.com",
"beacon":"{\"server\":\"api.kontakt.io\",\"apiKey\":\"ibZWPUctxIkkwMujyetstEYrxsVqiMrU\",
\"apiVersion\":10,\"enabled\":true,\"uuid\":\"f7826da6-4fa2-4e98-8024-bc5b71e0893e\"}",
"jwt":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDYzNjYzNDMsImV4cCI6MTUwODk1ODM0M
ywidXNlciI6ImpvaG4uc21pdGhAdmlzY291bnQuY29tIiwicGhvbmVJZCI6IjlGNTgzOTVELTc5NjMtNDY5Qy1CQjhG
LTVDMzlBMzFCMkI2WiJ9.CwYgbG2aoFTMjz7POKvckCnxf7MOB6tyR46idIPJuO0",
"phone-id":"9F58395D-7963-469C-BB8F-5C39A31B2B6Z",
"status":"ok",
"zoneAccess":2,
"refreshToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDYzNjYzNDMsImV4cCI6MTUy
MTkxODM0MywidXNlciI6ImpvaG4uc21pdGhAdmlzY291bnQuY29tIiwicGhvbmVJZCI6IjlGNTgzOTVELTc5NjMtNDY
5Qy1CQjhGLTVDMzlBMzFCMkI2WiJ9.tpDVdj8c2S4J6cHHj8_rJ4aIov7aq6lzGiUg_fhkwWE"
}Error responses
Incorrect email or password
HTTP 401 Unauthorized
Exceed mobile device limit on user or system
HTTP 400 Bad Request
{"status":400,"message":"Unable to register mobile device due to licensing, please contact system administrator."}
Login Using Access Token
This chapter describes how to login to Primis using the access token.
Request Header:
Method | URI | Authorization | Comments |
POST | /api/mobile/access_token/login | Bearer authentication | Bearer authentication using access token returned by the operation in Chapter 2 Register/Login. |
Request Body:
JSON Property Name | Type | Description | Comments |
phoneId | String | Unique identifier for the mobile device | The phoneId is assigned by the mobile application. |
Response Body:
JSON Property Name | Type | Description | Comments |
registered | Boolean | Always return true |
|
isAdmin | Boolean | Indicate whether the user is a Primis administrator |
|
String | Email address of the user |
| |
beacon | JSON Object | Beacon configuration in Primis |
|
jwt | String | Access token | Access token for accessing the Primis Mobile API. |
phone-id | String | Unique identifier for the mobile device |
|
status | String | Result status of the operation | “ok” if the operation is successful |
zoneAccess | Number | User access privilege on controlled area configuration | 0 – no access to controlled area configuration |
Login using access token
POST /api/mobile/access_token/login
https://<ip address>:<api listening port>/api/mobile/access_token/login
Content-Type: application/json
Post Data:
{"phoneId": "9F58395D-7963-469C-BB8F-5C39A31B2B6Z"}
Response Data:
{
"registered":true,
"isAdmin":true,
"email":"john.smith@identiv.com",
"beacon":"{\"server\":\"api.kontakt.io\",\"apiKey\":\"ibZWPUctxIkkwMujyetstEYrxsVqiMrU\",
\"apiVersion\":10,\"enabled\":true,\"uuid\":\"f7826da6-4fa2-4e98-8024-bc5b71e0893e\"}",
"jwt":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDYzNjYzNDMsImV4cCI6MTUwODk1ODM0M
ywidXNlciI6ImpvaG4uc21pdGhAdmlzY291bnQuY29tIiwicGhvbmVJZCI6IjlGNTgzOTVELTc5NjMtNDY5Qy1CQjhG
LTVDMzlBMzFCMkI2WiJ9.CwYgbG2aoFTMjz7POKvckCnxf7MOB6tyR46idIPJuO0",
"phone-id":"9F58395D-7963-469C-BB8F-5C39A31B2B6Z",
"status":"ok",
"zoneAccess":2
}Error responses
Invalid access token
HTTP 401 Unauthorized
Renew Access Token
This chapter describes how to renew the access token using the refresh token.
Request Header:
Method | URI | Authorization | Comments |
POST | /api/mobile/access_token | Bearer authentication | Bearer authentication using refresh token returned by the operation in Chapter 2 Register/Login. |
Request Body:
JSON Property Name | Type | Description | Comments |
{} | JSON Object | Empty JSON object |
|
Response Body:
JSON Property Name | Type | Description | Comments |
jwt | String | Access token | A new access token for accessing the Primis Mobile API. |
status | String | Result status of the operation | “ok” if the operation is successful. |
String | Email address of the user |
| |
phone-id | String | Unique identifier for the mobile device |
|
Renew access token
POST /api/mobile/access_token
https://<ip address>:<api listening port>/api/mobile/access_token
Content-Type: application/json
Post Data:
{ }
Response Data:
{
"jwt":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDYzNjY5MzMsImV4cCI6MTUwODk1ODkzMy
widXNlciI6ImpvaG4uc21pdGhAdmlzY291bnQuY29tIiwicGhvbmVJZCI6IjlGNTgzOTVELTc5NjMtNDY5Qy1CQjhGLT
VDMzlBMzFCMkI2WiJ9.U-kOms6kA67ZiPw4SdC3lpz0ES2VpzxX84da8alD104",
"status":"ok",
"email":"john.smith@identiv.com",
"phone-id":"9F58395D-7963-469C-BB8F-5C39A31B2B6Z"
} Error responses
Invalid refresh token
HTTP 401 Unauthorized
Deregister Mobile Device
This chapter describes how to deregister a registered mobile device from Primis.
Request Header:
Method | URI | Authorization | Comments |
DELETE | /api/mobile/registration | Basic authentication or Bearer authentication | Basic authentication using the user email and password. |
Request Body:
JSON Property Name | Type | Description | Comments |
phoneId | String | Unique identifier for the mobile device |
|
Response Body:
JSON Property Name | Type | Description | Comments |
status | String | Result status of the operation | “ok” if the operation is successful |
Deregister mobile device
DELETE /api/mobile/registration
https://<ip address>:<api listening port>/api/mobile/registration
Content-Type: application/json
Request Data:
{"phoneId": "9F58395D-7963-469C-BB8F-5C39A31B2B6Z"}
Response Data:
{"status":"ok"}
Error responses
Invalid email/password or refresh token
HTTP 401 Unauthorized
Change User Password
This chapter describes how to change the password for mobile user.
Request Header:
Method | URI | Authorization | Comments |
POST | /api/mobile/password | Basic authentication or Bearer authentication | Basic authentication using the user email and password. |
Request Body:
JSON Property Name | Type | Description | Comments |
newPassword | String | New user password | Password must be at least one number, one lowercase, one uppercase letter and at least six characters. |
Response Body:
JSON Property Name | Type | Description | Comments |
status | String | Result status of the operation | “ok” if the operation is successful |
Message | String | Result message of the operation |
|
Change user password
POST /api/mobile/password
https://<ip address>:<api listening port>/api/mobile/password
Content-Type: application/json
Request Data:
{"newPassword": "Password1234"}
Response Data:
{"status":"ok","message":"Password successfully updated"}
Error responses
Invalid email/password or refresh token
HTTP 401 Unauthorized
Invalid new password
HTTP 400 Bad Request
{"status":400,"message":"Password must be at least one number, one lowercase, one uppercase letter and at least six characters"}
Access Using Geolocation Data
This chapter describes how to request access using the geolocation data. Beacon or GPS geolocation are supported.
Request Header:
Method | URI | Authorization | Comments |
POST | /api/mobile/geolocation/access | Bearer authentication | Bearer authentication using access token returned by the operation in Chapter 2 |
Request Body:
JSON Property Name | Type | Description | Comments | |
guid | String | Unique identifier for the mobile device |
| |
beacon | JSON Object |
| Either the beacon or gps JSON property should be presented in the request. | |
| uuid | String | Unique identifier of the beacon |
|
major | Number | Major number of the beacon |
| |
minor | Number | Minor number of the beacon |
| |
gps | JSON Object |
| Either the beacon or gps | |
| latitude | Number | Latitude coordinate of the mobile device |
|
longitude | Number | Longitude coordinate of the mobile device |
| |
Response Body:
JSON Property Name | Type | Description | Comments | |
|---|---|---|---|---|
status | String | Result status of the operation | “ok” if API successfully called Primis for the access request. | |
primisResult | JSON Object | Result of the operation at Primis |
| |
| result | String | Result of the access request | “denied” - access request is denied |
| zoneid | String | Unique identifier of the controlled area which the user is accessing |
|
| zonename | String | Name of the controlled area which the user is accessing |
|
| distance | Number | Distance of the mobile device from the beacon | Only return on access request with GPS data |
| info | String | Addition information |
|
Access request with Beacon data
POST /api/mobile/geolocation/access
https://<ip address>:<api listening port>/api/mobile/geolocation/access
Content-Type: application/json
Request Data:
Response Data:
{"status":"ok","primisResult":{"result":"granted","zoneid":"110000000000","zonename":"Factory Floor","info":""}}
Access request with GPS data
POST /api/mobile/geolocation/access
https://<ip address>:<api listening port>/api/mobile/geolocation/access
Content-Type: application/json
Request Data:
{"guid":"9F58395D-7963-469C-BB8F-5C39A31B2B6Z", "gps": "latitude":49.1885195,"longitude":-122.99220389999999}}
Response Data:
{"status":"ok","primisResult":{"result":"granted","zoneid":"110000000001","zonename":"Lobby","distance":0.0,"i nfo":""}}
Error responses
Access denied
HTTP 201 Created
{"status":"ok","primisResult":{"result":"denied","zoneid":"110000000001","zonename":"Lobby","distance":55.597463321754745,"info":"Unable to find controlled areas nearby"}}
Update Beacon Status
This chapter describes how to update the beacon status in Primis.
Request Header:
Method | URI | Authorization | Comments |
POST | /api/mobile/beacon/status | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. |
Request Body:
JSON Property Name | Type | Description | Comments |
major | Number | Major number of the beacon |
|
minor | Number | Minor number of the beacon |
|
batteryLevel | Number | Battery level of the beacon, in percentage |
|
Response Body:
JSON Property Name | Type | Description | Comments |
status | String | Result status of the operation | “ok” if the operation is successful |
primisResult | JSON Object | Always empty |
|
Update beacon status
POST /api/mobile/beacon/status
https://<ip address>:<api listening port>/api/mobile/beacon/status
Content-Type: application/json
Request Data:
{"major":1,"minor":3, "batteryLevel": 76}
Response Data:
{"status":"ok","primisResult":{}}
Beacons
This chapter describes how to retrieve Beacon(s) through the PRIMIS Mobile API software.
Request Header:
Method | URI | Authorization | Comments |
GET | /api/mobile/beacons | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. Return all beacons in the system. |
GET | /api/mobile/beacon/<beaconId> | Bearer authentication | Bearer authentication using the Access Token returned by the operation in Chapter 2 Register/Login. Return the beacon specified. |
Request Body: None
Response Body:
JSON Property Name | Type | Description | Comments |
uniqueId | String | Unique ID of the beacon |
|
major | Number | Major number of the beacon |
|
minor | Number | Minor number of the beacon |
|
uuid | String | Universal Unique Identifier of the beacon |
|
advInterval | Number | Advertising interval of the beacon |
|
avgEventInterval | Number | Average time between Beacon Health check |
|
lastEventTimestamp | String | Timestamp of the last scan made by a Beacon Health enabled app or device |
|
batteryLevel | Number | Device’s battery level in percentage |
|
master | String | Unique ID of a Cloud Beacon responsible for this device |
|
updatedAt | String | Timestamp of the last update on the beacon device record |
|
deviceData | JSON Object | Raw beacon device data |
|
statusData | JSON Object | Raw beacon status data |
|
List all beacons
GET /api/mobile/beacons
https://<ip address>:<api listening port>/api/mobile/beacons
Result:
Get a beacon record by id
GET /api/mobile/beacon/<beaconId>
https://<ip address>:<api listening port>/api/mobile/beacon/rLxR
Result:
Controlled Areas
This chapter describes how to retrieve controlled areas accessible by the mobile user through the PRIMIS Mobile API software.
Request Header:
Method | URI | Authorization | Comments |
For mobile user who is a Primis administrator | |||
GET | /api/mobile/<phoneId>/ controlled_areas | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. The mobile user must be Primis administrator in order to use this operation. |
For mobile user | |||
GET | /api/mobile/controlled_ areas | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. |
Request Body: None
Response Body: array of the following JSON Object
JSON Property Name | Type | Description | Comments | ||
|---|---|---|---|---|---|
id | String | Unique identifier of the controlled area |
| ||
name | String | The name of the controlled area |
| ||
description | String | The description of the controlled area |
| ||
toggle | String | When toggle is set to “T”, the controlled area will remain off or on indefinitely when its state is changed. This disables activation times for the controlled area and toggles the state of the controlled area indefinitely. | T – toggle | ||
factor | Number | Multi-factor settings for authorization | 0 – not multi factor | ||
authorizationTimout | Number | Time out in seconds for multi-factor authorization |
| ||
authorizationMode | Number | Multi-factor authorization mode | 0 – single user | ||
guardGroup | String |
| Deprecated | ||
state | String | The state of the controlled area | open – the relay is opened | ||
zoneGroupId | String | The zone group which the controlled area is assigned to. | “” – not assigned to any zone group | ||
siteId | String | The site identifier |
| ||
geoLocation | JSON Object | Geolocation data |
| ||
| enabled | Boolean | The controlled area is configured to support access with Geolocation data. |
| |
beacon | JSON Object | Beacon configuration |
| ||
| uniqueId | String | Unique identifier of the beacon |
| |
major | Number | Major number of the beacon |
| ||
minor | Number | Minor number of the beacon |
| ||
gps | JSON Object | GPS configuration |
| ||
| latitude | Number | Latitude coordinate of the controlled area |
| |
longitude | Number | Longitude coordinate of the controlled area |
| ||
unitType | String | Unit of radius |
| ||
radius | Number | Radius from the latitude/longitude coordinate of the controlled area | Primis will deny the access request with GPS data if the mobile user is located outside of the radius from the latitude/longitude coordinate of the controlled area. | ||
List controlled areas accessible by the mobile user
GET /api/mobile/<phoneId>/controlled_areas
https://<ip address>:<api listening port>/api/mobile/9F58395D-7963-469C-BB8F- 5C39A31B2B6Z/controlled_areas
Result:
Access Groups
This chapter describes how to retrieve access groups assigned to the mobile user through the PRIMIS Mobile API software.
Request Header:
Method | URI | Authorization | Comments |
For mobile user who is a Primis administrator | |||
GET | /api/mobile/<phoneId>/ access_groups | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. The mobile user must be Primis administrator in order to use this operation. |
For mobile user | |||
GET | /api/mobile/access_groups | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. |
Request Body: None
Response Body: array of the following JSON Object
JSON Property Name | Type | Description | Comments |
id | String | Unique identifier of the access group |
|
name | String | Name of the access group |
|
description | String | Description of the access group |
|
site_id | String | The ID of the Site which the access group is defined at |
|
List access groups assigned to the mobile user
GET /api/mobile/<phoneId>/access_groups
https://<ip address>:<api listening port>/api/mobile/9F58395D-7963-469C-BB8F- 5C39A31B2B6Z/access_groups
Result:
[{"id":3,"name":"Staff","description":"","site_id":"1"},{"id":545,"name":"Management","description":"","site_id ":"1"}]
Update Controlled Area State
This chapter describes how to set the state of controlled area(s) through the PRIMIS Mobile API software.
Request Header:
Method | URI | Authorization | Comments |
POST | /api/mobile/zone_state | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. The mobile user must be Primis administrator in order to use this operation. Only one controlled area can be updated by this operation. |
POST | /api/mobile/zone_states | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. The mobile user must be Primis administrator in order to use this operation. Multiple controlled areas can be updated by this operation. |
Request Body:
JSON Property Name | Type | Description | Comments |
zone-id | String | Unique identifier of the controlled area |
|
State | Number | State of the controlled area | 11 – Open |
Response Body:
JSON Property Name | Type | Description | Comments |
status | String | “ok” if API successfully called Primis to perform the operation |
|
result | String | “Granted” is the peration is successful |
|
Update controlled area state (single controlled area)
POST /api/mobile/zone_state
https://<ip address>:<api listening port>/api/mobile/zone_state
Post Data:
{"zone-id": "130000000001","state": 12}
Result:
{"status":"ok","result":"Granted"}
Update controlled area state (multiple controlled areas)
POST /api/mobile/zone_states
https://<ip address>:<api listening port>/api/mobile/zone_states
Post Data:
Result:
[{"status":"ok","result":"Granted"},{"status":"ok","result":"Granted"}]
Momentary Unlock Controlled Area
This chapter describes how to momentary unlock controlled area(s) through the PRIMIS Mobile API software.
Request Header:
Method | URI | Authorization | Comments |
|---|---|---|---|
For mobile user who is Primis administrator | |||
POST | /api/mobile/unlock_zone | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. The mobile user must be Primis administrator in order to use this operation. Only one controlled area can be specified in this operation. |
POST | /api/mobile/unlock_zones | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. The mobile user must be Primis administrator in order to use this operation. Multiple controlled areas can be specified in this operation. |
For mobile user | |||
POST | /api/mobile/user/unlock_ zone | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. Only one controlled area can be specified in this operation and the controlled area must be accessible by the user. |
POST | /api/mobile/user/unlock_ zones | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. |
Request Body:
JSON Property Name | Type | Description | Comments |
zone-id | String | Unique identifier of the controlled area |
|
duration | Number | Number of seconds that the controlled area will be momentary unlocked |
|
Response Body:
JSON Property Name | Type | Description | Comments |
status | String | “ok” if API successfully sent the request to Primis |
|
result | String | “Granted” if the operation is successful |
|
Momentary unlock a controlled area
POST /api/mobile/unlock_zone
https://<ip address>:<api listening port>/api/mobile/unlock_zone
Post Data:
{"zone-id": "150000000003", "duration":10 }
Result:
{"status":"ok","result":"Granted"}
Momentary unlock multiple controlled areas
POST /api/mobile/unlock_zones
https://<ip address>:<api listening port>/api/mobile/unlock_zones
Post Data:
[{"zone-id": "130000000001", "duration":10 }, {"zone-id": "150000000003", "duration":10}]
Result:
[{"status":"ok","result":"Granted"},{"status":"ok","result":"Granted"}]
Create Controlled Area Schedule
This chapter describes how to create the controlled area schedule through the PRIMIS Mobile API software.
Request Header:
Method | URI | Authorization | Comments |
POST | /api/controlled_area_sch edules/schedule | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. The mobile user must be Primis administrator in order to use this operation. |
Request Body:
JSON Property Name | Type | Description | Comments | |
id | Number | Unique identifier of the schedule |
| |
zones | Array of JSON object |
|
| |
| controlled_area_id | String | Unique identifier of the controlled area |
|
on_action | Number | Action when the schedule is on | 1 – Open | |
off_action | Number | Action when the schedule is off | 1 – Open | |
description | String | Description of the controlled area schedule |
| |
Response Body:
JSON Property Name | Type | Description | Comments | |
id | Number | Unique identifier of the schedule |
| |
name | String | Name of the schedule |
| |
description | String | Description of the schedule |
| |
zones | Array of JSON object |
|
| |
| id | String | Unique identifier of the controlled area schedule |
|
| controlled_area_id | String | Unique identifier of the controlled area |
|
| on_action | Number | Action when the schedule is on |
|
| off_action | Number | Action when the schedule is off |
|
| description | String | Description of the controlled area schedule |
|
Create controlled area schedules
POST /api/controlled_area_schedules/schedule
https://<ip address>:<api listening port>/api/controlled_area_schedules/schedule
Post Data:
Result:
Controlled Areas By Access Group
This chapter describes how to retrieve the controlled areas accessible by an access group through the PRIMIS Mobile API software.
Request Header:
Method | URI | Authorization | Comments |
GET | /api/access_groups/<accessGroupId>/controlled_ar eas_detail | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. The mobile user must be Primis administrator in order to use this operation. |
Request Body: None
Response Body: array of the following JSON Object
JSON Property Name | Type | Description | Comments | ||
|---|---|---|---|---|---|
id | String | Unique identifier of the controlled area |
| ||
name | String | The name of the controlled area |
| ||
description | String | The description of the controlled area |
| ||
toggle | String | When toggle is set to “T”, the controlled area will remain off or on indefinitely when its state is changed. This disables activation times for the controlled area and toggles the state of the controlled area indefinitely. | T – toggle | ||
factor | Number | Multi-factor settings for authorization | 0 – not multi factor | ||
authorizationTimout | Number | Time out in seconds for multi-factor authorization |
| ||
authorizationMode | Number | Multi-factor authorization mode | 0 – single user | ||
guardGroup | String |
| Deprecated | ||
state | String | The state of the controlled area | open – the relay is opened LOCKDOWN – no access is allowed | ||
zoneGroupId | String | The zone group which the controlled area is assigned to. | “” – not assigned to any zone group | ||
siteId | String | The site identifier |
| ||
geoLocation | JSON Object | Geolocation data |
| ||
| enabled | Boolean | The controlled area is configured to support access with Geolocation data. |
| |
gps | JSON Object | GPS configuration |
| ||
| latitude | Number | Latitude coordinate of the controlled area |
| |
longitude | Number | Longitude coordinate of the controlled area |
| ||
unitType | String | Unit of radius |
| ||
radius | Number | Radius from the latitude/longitude coordinate of the controlled area | Primis will deny the access request with GPS if the mobile user is located outside of the radius from the latitude/ ongitude coordinate of the controlled area. | ||
beacon | JSON Object | Beacon configuration |
| ||
| uniqueId | String | Unique identifier of the beacon |
| |
major | Number | Major number of the beacon |
| ||
minor | Number | Minor number of the beacon |
| ||
List controlled areas by access group
GET /api/access_groups/<accessGroupId>/controlled_areas_detail
https://<ip address>:<api listening port>/api/access_groups/3/controlled_areas_detail
Result:
Schedules
This chapter describes how to retrieve schedules assigned to the mobile user through the PRIMIS Mobile API software.
Request Header:
Method | URI | Authorization | Comments |
GET | /api/mobile/schedules | Bearer authentication | Bearer authentication using the access token returned by the operation in Chapter 2 Register/Login. |
Request Body: None
Response Body: array of the following JSON Object
JSON Property Name | Type | Description | Comments | |
|---|---|---|---|---|
id | String | Unique identifier of the schedule |
| |
name | String | Name of the schedule |
| |
description | String | Description of the schedule |
| |
siteId | String | The ID of the Site which the schedule is defined at |
| |
usedByAccessGroup | Boolean | True if the schedule is used by User Access Group |
| |
periods |
|
|
| |
| id | String | Unique identifier for a Schedule Period |
|
| frequency | Number | The frequency of the Schedule Period | This field is a bit mask of the two types - weekly and holiday. When weekly is used, this field has the value of 0x00002 (decimal 2). When holiday type is used, the lower two bytes has the value of 0x00040 (decimal 64), the upper 3 bytes represents the holiday type in used. Each bit in these 3 upper bytes present one holiday type enumerated like the following: |
| exceptions | Number | The exception holiday types in the Schedule Period | This field is a bit mask that maintains the exception holiday types in the schedule period. The types are enumerated the same way as the types 1 through to 12 in frequency (0x00100, 0x00200.... 0x80000). |
| days | Number | The days of the week that are active in the Schedule Period | This field is a bit mask that maintains the days of the week that are active in the schedule period. Day-of-the-week bit masks are enumerated in the follow way: |
| on_time | String | The effective start date of the Schedule Period | 1900-01-01 00:00:00.0 will be returned if no start date is specified |
| off_time | String | The effective expire date of the Schedule Period | 1900-01-01 00:00:00.0 will be returned if no expire date is specified |
| enabled | Number |
| Deprecated |
List schedules assigned to the mobile user
GET /api/mobile/schedules
https://<ip address>:<api listening port>/api/mobile/schedules
Result:
|
GLOSSARY
TERM | DEFINITION |
Access Group | Access Group is the logical grouping of users which you can assign Access Right to. |
Administrator | An individual who is responsible for the maintenance and implementation of access control rights involving tasks such as issuing, and closing user accounts; tracking users and their respective access authorizations; and managing these functions. |
Controlled Area | Controlled Area is an area being controlled by one or more input or output devices such as Primis Bridge readers. |
Schedule | A schedule is a given period of time that is applied to Controlled Areas and Access Groups and used to schedule device activation and alarms. |
Site | A geographical grouping of controlled area(s). |
User | An individual whose access privilege to controlled areas are managed by PRIMIS. |