{"mock":"https://private-anon-bb042af21e-v2accessmanageradmin.apiary-mock.com/","production":"https://access.telcred.com/","proxy":"https://private-anon-bb042af21e-v2accessmanageradmin.apiary-proxy.com/"}

FORMAT: 1A HOST: https://access.telcred.com/ # v2 Telcred Access Manager Admin API <!-- https://docs.oracle.com/cloud/apiary/faq/commonmark/ --> This API allows you to administer access rights in Telcred Access Manager. Before you start, you need to have at least one system ID, one organization ID, and the sign in credentials (user name and password) for one officer with administrator capacity. ## Version upgrades In the front of the URL for all requests you will find v2 which is the identifier for this version of the API, and we will never make backwards-incompatible changes to it. When we need to change the API in a backwards-incompatible way, we release a new version, with a completely new set of URLs. You may continue to use the v2 URLs for as long as they are available. This avoids code changes on your part, until you are ready to upgrade. ## Backwards-compatible changes Telcred considers the following changes to be backwards-compatible, so your implementations should handle them gracefully: + Adding new API resources. + Adding new optional query parameters to existing API resources. + Adding new optional properties to the bodies of existing API requests. + Adding new properties to the bodies of existing API responses. + Extending the set of possible values of a property, e.g. adding new reasons for events. ## Using the API ### Authentication All requests are authenticated using HTTP Basic Auth. Any officer with administrator capacity can be used. You can match this to users of the client system or have a dedicated API user as you see fit. ### Naming The object types Authorization, Token, and Policy, are called Role, Device, and Privilege in the Access Manager UI. ### Request and response body The body of a request or a response is either a single object or an array of objects. In actions that include both a request and a response object, the type of the object will be the same, e.g. creating a user takes a user as input and returns a user as output. However, while the response will include all attributes of the object, it is usually not necessary to include all the attributes in the request. ### Content types The content type for both request body and response body is application/json. ### Status codes For a request that has been processed without error, the response status code is 200. If processing the request fails, the response status code is always 400. See the section [Error Responses](#/introduction/error-responses). ## Understanding the API specification This documentation is structured by resource (controllers, users, ...). Each section starts out by listing the actions (list, create, ...) that can be performed on the resource, specifying the HTTP method, the URL, the request body, and the response body, for each. For example, in the Users section | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/users | | array[user] | declares that users are listed through a GET request that will return an array of user object. #### URL Parameters [urlparameters]: #/introduction/understanding-the-api-specification/url-parameters These parameters are used in URL specifications (see the example above): | Parameter | Explanation | |-----|-----| | sys | The id of the system. | | org | The id of the organization. | | id | The id of the target object if any. | The system id is provided by Telcred. The organization id is provided by Telcred, but can also be found through the [Telcred Access Manager Owner API](https://v2accessmanagerowner.docs.apiary.io). The ids for the target objects are provided in the API responses below. #### Object Attributes The specification of the attributes lists them as mandatory, optional, or ignored: + mandatory: + In create requests, a value must be provided. + In update requests, the attribute is optional. + optional: A value may be provided when relevant. + In create requests, when omitted, unless otherwise noted, a single value will default to null and an array value will default to an empty array. + In update requests, when omitted, the existing value will remain unchanged. + ignored: only relevant in responses, a value provided in a request will be disregarded. The specification of the attributes also declare their types. Types may be the native JSON types number, boolean, string, array, or another object. Such embedded objects are either described in the same section or are of the type Object Reference. #### The Object Reference object The Object Reference object is frequently used in place of any object with an id, representing that object. It only has one mandatory attribute, the id. The name of the referenced object is included as a second and final attribute. This name attribute is ignored rather than mandatory, so it does not have to be supplied in requests, but it will be supplied in responses, as a convenience. This is the specification of the Object Reference object: ``` { "id": "196458", "name": "Alice Smith" } ``` This is the specification of the attributes: ##### **id** (string) _mandatory_ The id of the object. ##### **name** (string) _ignored_ The name of the object. ## Examples The following requests are performed using officer "officer", with password "password", for authorization. Create a user named Alice, in system 1, organization 4043: <pre><code> curl -X POST -H "Content-Type: application/json" \ -u officer:password \ https://access.telcred.com/v2/sys/1/org/4043/users \ -d '{"name": "Alice Smith"}' </code></pre> Response body: ``` { "id": "318069", "authorizations": [ ], "blocked": false, "name": "Alice Smith", "pin": null, "tokens": [ ] } ``` Note 1: that although the object type (user) of the response is also required for the request, only the name attribute is mandatory and has to be provided. Note 2: that the response includes the full set of attributes. This is always the case. Create a token for Alice using the id from the response above: <pre><code> curl -X POST -H "Content-Type: application/json" \ -u officer:password \ https://access.telcred.com/v2/sys/1/org/4043/tokens \ -d '{"name": "Alice Badge", "type": "CID", "cid": "AABBCCDDEE", "user": {"id": "318069"}}' </code></pre> Response body: ``` { "id": "80954", "blocked": false, "cid": "AABBCCDDEE", "description": null, "name": "Alice Badge", "type": "CID", "user": { "id": "318069", "name": "Alice Smith" }, "userFrom": null, "userTo": null } ``` Note 1: the use of the Object Reference to denote the previously created user. Note 2: that in the Object Reference, only the id attribute is mandatory and has to be provided in the request. Update Alice with a PIN code: <pre><code> curl -X PUT -H "Content-Type: application/json" \ -u officer:password \ https://access.telcred.com/v2/sys/1/org/4043/users/318069 \ -d '{"pin": "1106"}' </code></pre> Response body: ``` { "id": "318069", "authorizations": [ ], "blocked": false, "name": "Alice Smith", "pin": "1106", "tokens": [ { "id": "80954", "name": "Alice Badge", "userFrom": null, "userTo": null } ] } ``` Note 1: that only the attributes (pin) to be changed was provided in the request. Note 2: in a few cases, a richer object than the regular Reference Object is used. Retrieve token 80954 referenced in the response above: <pre><code> curl -X GET \ -u officer:password \ https://access.telcred.com/v2/sys/1/org/4043/tokens/80954 </code></pre> Response body: ``` { "id": "80954", "blocked": false, "cid": "AABBCCDDEE", "description": null, "name": "Alice Badge", "type": "CID", "user": { "id": "318069", "name": "Alice Smith" }, "userFrom": null, "userTo": null } ``` Delete the token with id 80954: <pre><code> curl -X DELETE \ -u officer:password \ https://access.telcred.com/v2/sys/1/org/4043/tokens/80954 </code></pre> Note: the response has no body in this case. List all tokens: <pre><code> curl -X GET \ -u officer:password \ https://access.telcred.com/v2/sys/1/org/4043/tokens/ </code></pre> Response body: ``` [ ] ``` Note: If there are none, the response body will be an empty list. List all users: <pre><code> curl -X GET \ -u officer:password \ https://access.telcred.com/v2/sys/1/org/4043/users/ </code></pre> Response body: ``` [ { "id": "318069", "authorizations": [ ], "blocked": false, "name": "Alice Smith", "pin": "1106", "tokens": [ ] } ] ``` ---------------------------- <div style="font-size:30px;text-align:center">Resources</div> ---------------------------- ## Authorizations "Authorizations" are known as "Roles" in the Access Manager UI. | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/authorizations | | array[authorization] | | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/authorizations | authorization | authorization | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/authorizations/[id][urlparameters] | | authorization | | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/authorizations/[id][urlparameters] | authorization | authorization | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/authorizations/[id][urlparameters] | | | ### Authorization object ``` { "id": "authorization1", "name": "IT technician", "type": "ROLE", "validFrom": 0, "validTo": 3155760000000, "policies": [ { "id": "policy1", "name": "Ground floor - office hours" }, { "id": "policy2", "name": "Ground floor - weekends" } ], "users": [ { "id": "user1", "name": "Alan Smith" }, { "id": "user2", "name": "Bob Dole" } ] } ``` ### Authorization attributes ##### **id** (string) _ignored_ The id of the authorization. ##### **name** (string) _mandatory_ The name of the authorization. ##### **type** (string) _optional_ Legacy attribute which is no longer in use. One of ROLE or ASSIGNMENT. Defaults to ROLE. ##### **validFrom** (number) _mandatory_ Validity start in milliseconds from 1970-01-01T00:00:00 in the time zone of the controller. ##### **validTo** (number) _mandatory_ Validity end in milliseconds from 1970-01-01T00:00:00 in the time zone of the controller. ##### **policies** (array[object reference]) _optional_ The policies this authorization provides. ##### **users** (array[object reference]) _optional_ The users with this authorization. ## Controllers | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/controllers | | array[controller] | | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/controllers | controller | controller | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/controllers/[id][urlparameters] | | controller | | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/controllers/[id][urlparameters] | controller | controller | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/controllers/[id][urlparameters] | | | ### Controller object ``` { "id": "controller1", "name": "Entrance controller", "description": null, "type": "A1001", "timeZone": "CET", "connectionMode": "DIRECT", "connectionState": "UNDEFINED", "connectionInfo": "No attempt to connect to the controller has been done yet.", "address": "3.71.41.255:23000", "mac": null, "internalIp": null, "fwVersion": null, "hub": { "id": "hub1", "name": "Entrance hub", "doors": [ { "id": "door2", "name": "Inner entrance door 1" }, { "id": "door3", "name": "Inner entrance door 2" } ] }, "locks": [ { "port": 1, "usage": "PRIMARY", "mode": "ENGAGE_FAIL_SAFE", "door": { "id": "door1", "name": "Entrance door" } }, { "port": 2, "usage": "SECONDARY", "mode": "ENGAGE_FAIL_SAFE", "door": { "id": "door1", "name": "Entrance door" } } ], "monitors": [ { "port": 1, "type": "OPEN_CIRCUIT_OPEN_DOOR", "door": { "id": "door1", "name": "Entrance door" } } ], "readers": [ { "port": 3, "type": "RS485_HD_OSDP", "door": { "id": "door1", "name": "Entrance door" }, "inside": false } ], "rexButtons": [ { "port": 1, "type": "CLOSING_CIRCUIT_TRIGGERS", "door": { "id": "door1", "name": "Entrance door" } } ], "ioPort": [ { "port": 1, "type": "IN_NG" } ] } ``` ### Controller attributes ##### **id** (string) _ignored_ The id of the controller. ##### **name** (string) _mandatory_ The name of the controller. ##### **type** (string) _mandatory_ The controller model. One of + "A1001": Denotes the Axis A1001. + "A1601": Denotes the Axis A1601. + "A9161": Denotes the Axis A9161. ##### **timeZone** (string) _mandatory_ The time zone of the controller, represented as a string. This string must be the canonical ID of the desired time zone as defined by the tz database. A full list of supported time zones with canonical IDs can be found here: [http://joda-time.sourceforge.net/timezones.html][]. ##### **connectionMode** (string) _mandatory_ How the controller is reached over the network. One of + DIRECT: if the controller is connected directly via its IP address. + O3C: if the controller is connected via the One-Click connection service. Do note that configuration to the One-Click connection service is done separately via its own API. + SHORTCUT: if the controller is connected via a shortcut. See Shortcut Generators in the Owners API. ##### **connectionState** (string) _ignored_ The current state of the connection to the controller as of the last attempt to connect. One of + CONNECTED: if the latest attempt to connect to the controller succeeded. + DISCONNECTED: if the latest attempt to connect to the controller failed. + UNCONFIGURED: if the connection details for this controller have not been provided. + UNDEFINED: if connection to the controller has not been attempted yet. ##### **connectionInfo** (string) _ignored_ Details regarding the connection state intended for human consumption. ##### **address** (string) _optional_ How to reach the controller if connectionMode is not O3C. + If connectionMode is DIRECT, the format is 'ip:port', e.g. `192.168.1.1:43` + If connectionMode is SHORTCUT, the format is 'shortcut name:external controller id', e.g. `demo:43`. ##### **mac** (string) _ignored_ The MAC address retrieved from the controller (if connection to the controller has worked). ##### **internalIp** (string) _ignored_ The local IP address retrieved from the controller (if connection to the controller has worked). ##### **fwVersion** (string) _ignored_ The version of the firmware currently running the controller. ##### **hub** (hub reference) _optional_ The hub connected to this controller. ##### **locks** (array[lock]) _optional_ The array of all locks connected to the controller. ##### **monitors** (array[monitor]) _optional_ The array of all door monitors connected to the controller. ##### **readers** (array[reader]) _optional_ The array of readers connected to this controller. ##### **rexButtons** (array[rex button]) _optional_ The array of Request-To-Exit (REX) buttons connected to this controller. ##### **ioPorts** (array[io port]) _optional_ The array of IO ports configured on this controller. ### Hub reference attributes ##### **id** (string) _mandatory_ The id of the hub. ##### **name** (string) _ignored_ The name of the hub. ##### **doors** (array[object reference]) _ignored_ The doors controlled by this hub. ### Lock attributes ##### **port** (number) _mandatory_ A number that denotes the hardware terminals assigned for this lock. + Axis A1001: 1 for LOCK pin H1, 2 for LOCK pin H2, or 3 for RELAY|PWR/REL. + Axis A1601: 1 for RELAY 1, or 2 for RELAY 2. ##### **usage** (string) _mandatory_ One of + PRIMARY: If the lock is the primary lock. + SECONDARY: If the lock is the secondary lock. ##### **mode** (string) _mandatory_ The mapping between port behavior and locked/unlocked. One of + ENGAGE_FAIL_SAFE: port or relay powered up when locked. + ENGAGE_FAIL_SECURE: port or relay powered down when locked. ##### **door** (object reference) _mandatory_ The door this lock is connected to. ### Monitor attributes ##### **port** (number) _mandatory_ A number that denotes the hardware terminals assigned for this monitor. + Axis A1001: 1 for DOOR IN 1 pin IN1, or 2 for DOOR IN 2 pin IN3. + Axis A1601: 1 for DOOR 1 pin IO6, or 2 for DOOR 2 pin IO12. ##### **type** (string) _mandatory_ The operation mode of this door monitor. One of + OPEN_CIRCUIT_OPEN_DOOR: if the door monitor circuit is open when the door is open. + OPEN_CIRCUIT_CLOSED_DOOR: if the door monitor circuit is open when the door is closed. ##### **door** (object reference) _mandatory_ The door this monitor is connected to. ### Reader attributes ##### **port** (number) _mandatory_ A number that denotes the hardware terminals assigned for this reader. + Axis A1001: 1 for READER DATA 1 pin A- and pin B+, or 2 for READER DATA 2 pin A- and pin B+ + Axis A1601: 1 for READER 1 pin A/D0 and pin B/D1, or 2 for READER 2 pin A/D0 and pin B/D1 ##### **type** (string) _mandatory_ The type of this reader. One of + RS485_HD_OSDP: For RS485 half-duplex and OSDP. + WIEGAND_SINGLE_LED: For Wiegand protocol with a single LED. + WIEGAND_DUAL_LED: For Wiegand protocol with two LEDs. ##### **door** (object reference) _mandatory_ The door this reader is connected to. ##### **inside** (boolean) Whether the reader is mounted inside (true) or outside (false). Defaults to false. ### REX Button attributes ##### **port** (number) _mandatory_ A number that denotes the hardware terminals assigned for this REX Button. + Axis A1001: 1 for DOOR IN 1 pin IN2, or 2 for DOOR IN 2 pin IN4. + Axis A1601: 1 for DOOR 1 pin IO5, or 2 for DOOR 2 pin IO11. ##### **type** (string) _mandatory_ The operation mode of this REX button. One of + CLOSING_CIRCUIT_TRIGGERS: If activating the REX button closes the circuit. + OPENING_CIRCUIT_TRIGGERS: If activating the REX button opens the circuit. + CLOSING_CIRCUIT_TRIGGERS_NO_UNLOCK: Same as CLOSING_CIRCUIT_TRIGGERS but without unlocking. + OPENING_CIRCUIT_TRIGGERS_NO_UNLOCK: Same as OPENING_CIRCUIT_TRIGGERS but without unlocking. ##### **door** (object reference) _mandatory_ The door this REX button is connected to. ### IO Port attributes ##### **port** (number) _mandatory_ A number that denotes the hardware terminals assigned for this IO Port. + Axis A1001: 1 or 2 (for pins IO1 and IO2). + Axis A9161: 1 or 2 (for pins IO1 and IO2). + Axis A1601: 1, 2, 3, 4, 13, or 14 (for pins IO1, IO2,..., IO14). ##### **type** (string) _mandatory_ The configuration, one of + IN_NG: Input, deactivated by grounding. + IN_NO: Input, deactivated by leaving floating. + OUT_NG: Output, grounded when inactive. + OUT_NO: Output, floating when inactive. ## Controller Actions | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/controllers/[id][urlparameters]/action | controller action | controller action | Perform the reset or the restart actions on a controller with this request. ### Controller Action object ``` { "action": "RESET", "controller": { "id": "controller1", "name": "Entrance controller" } } ``` ### Controller Action attributes ##### **action** (string) _mandatory_ The action, one of RESET or RESTART. ##### **controller** (object reference) _mandatory_ The controller. ## Controller Firmware | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/controllers/[id][urlparameters]/firmware | controller firmware | controller firmware | Initiate a firmware update of a controller with this request. ### Controller Firmware object ``` { "version": "1.60.0", "controller": { "id": "controller1", "name": "Entrance controller" } } ``` ### Controller Firmware attributes ##### **version** (string) _mandatory_ Identifies one of the available firmware versions by name. ##### **controller** (object reference) _mandatory_ The controller. ## Controller Firmware Availability | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | Retrieve | GET | /v2/sys/[sys][urlparameters]/firmwareversions | | array[firmware availability] | Retrieve the names of the firmware versions available per controller type with this request. ### Firmware Availability object ``` { "controllerType": "A1001", "versions": [ "1.57", "1.60.0", "1.60.0.1" ] } ``` ### Firmware Availability attributes ##### **controllerType** (string) Identifies the controller type for which firmware is available. ##### **versions** (array[string]) A list of names that will identify the firmware versions that are available for the controller type. This list may be empty. ## Controller Pin Chart | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/controllers/[id][urlparameters]/pinchart | | array[pin chart] | Retrieve the current pin chart for a controller with this request. ### Pin Chart object Example 1 ``` { "device": "Entrance Lock 1", "connections": [ { "socket": "LOCK", "terminal": "-", "wire": "GND" }, { "socket": "LOCK", "terminal": "H1", "wire": "OUT" } ] } ``` Example 2 ``` { "device": "Entrance Reader 1", "connections": [ { "socket": "READER DATA 1", "terminal": "A-", "wire": "RX/TX B-" }, { "socket": "READER DATA 1", "terminal": "B+", "wire": "RX/TX A+" }, { "socket": "READER I/O 1", "terminal": "-", "wire": "GND" } ] } ``` ### Pin Chart attributes ##### **device** (string) The connected peripheral. ##### **connections** (array[connection]) How the peripheral is connected. ### Connection attributes ##### **socket** (string) The name of the socket on the controller. ##### **terminal** (string) The name of the terminal on the controller. ##### **wire** (string) The description of the terminal on the peripheral. ## Doors | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/doors | | array[door] | | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/doors | door | door | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/doors/[id][urlparameters] | | door | | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/doors/[id][urlparameters] | door | door | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/doors/[id][urlparameters] | | | ### Door object ``` { "id": "door1", "name": "Entrance door", "description": "Optional door description", "directional": false, "lockMode": "UNLOCKED", "lockState": "UNLOCKED", "lockStateOverride": "UNLOCKED", "doorMonitorState": "CLOSED", "controller": { "id": "anA1001", "name": "Entrance controller", "connectionState": "DISCONNECTED", "connectionInfo": "The latest request to the A1001 timed-out." }, "hub": { "id": "hub1", "name": "Entrance hub" }, "policies": [ { "id": "policy1", "name": "Ground floor - office hours" }, { "id": "policy2", "name": "Ground floor - weekends" } ], "visits": [ { "id": "visit1", "name": "May marketing event" } ], "doorGroups": [ { "id": "doorgroup1", "name": "Ground floor" }, { "id": "doorgroup2", "name": "Perimeter doors" } ], "accessSeconds": 7, "openTooLongSeconds": 30, "preAlarmSeconds": 10, "unlock": { "id": "schedule2", "name": "Open house hours" }, "unlockSecondary": { "id": "schedule1", "name": "Office hours" } } ``` ### Door attributes The following rules apply for the lockMode and lockStateOverride values: 1. Door.lockMode = Door.lockStateOverride if Door.lockStateOverride is not NONE, 2. else Door.lockMode = UNLOCKED if a schedule set in Door.unlock is active, 3. else Door.lockMode = LOCKED if a schedule set in Door.unlockSecondary is active, 4. else Door.lockMode = LOCKED if the door is configured with only one lock, 5. else Door.lockMode = DOUBLE_LOCKED. The following rules apply for the doorMonitorState value: 1. CLOSED may change to OPEN or FORCED_OPEN. 2. OPEN may change to CLOSED, OPEN_TOO_LONG, or FORCED_OPEN. 3. OPEN_TOO_LONG may only change to CLOSED. 4. FORCED_OPEN may only change to CLOSED. (Will not change to OPEN_TOO_LONG regardless of how long the door has been open). ##### **id** (string) _ignored_ The id of the door. ##### **name** (string) _mandatory_ The name of the door. ##### **description** (string) _mandatory_ The description of the door. ##### **directional** (false). Whether the door is directional (true) or not (false). Defaults to false. ##### **lockMode** (string) _ignored_ Determined by override, or if none by schedule, or if none defaults to LOCKED or DOUBLE_LOCKED dependent on the controller lock cofiguration. One of BLOCKED, UNLOCKED, LOCKED, DOUBLE_LOCKED, or UNKNOWN. ##### **lockState** (string) _ignored_ One of UNLOCKED, LOCKED, DOUBLE_LOCKED, UNKNOWN, or DETACHED. The value DETACHED applies only to wireless locks and means that the controller has lost contact with the lock. ##### **lockStateOverride** (string) _optional_ Override the influence of schedules on the lock mode. One of: + NONE is default and means that the door will be locked unless unlocked by a schedule. + BLOCKED means that the door is locked and that all requests for access will be denied. + UNLOCKED, LOCKED, DOUBLE_LOCKED: means that the lock shall always be in that state and that the attribute lockState shall have that value. This attribute can only be set in a separate PUT request after the door has been created. ##### **doorMonitorState** (string) _ignored_ May be CLOSED, OPEN, OPEN_TOO_LONG, FORCED_OPEN, or UNKNOWN. ##### **controller (controller connection) _ignored_ The door's controller if any. The controller is set through the controllers resource. ##### **hub** (object reference) _ignored_ The hub through which this door is connected to the controller, if any. The hub is set through the hubs resource. ##### **policies** (array[object reference]) _optional_ The list of policies that include this door. ##### **visits** (array[object reference]) _optional_ The list of visits that include this door. ##### **doorGroups** (array[object reference]) _optional_ The list of door groups that this controller is a member of. ##### **accessSeconds** (number) _optional_ The number of seconds a door will be accessible for after access is granted. Defaults to 0. ##### **openTooLongSeconds** (number) _optional_ The number of seconds that the door has to be held open to trigger an alarm. Defaults to 0. ##### **preAlarmSeconds** (number) _optional_ The number of seconds separating the pre-alarm from the door held open alarm. Defaults to 0. ##### **unlock** (object reference) _optional_ A schedule defining time periods when the door shall be unlocked. ##### **unlockSecondary** (object reference) _optional_ A schedule defining time periods when the secondary lock (if any) shall be unlocked. ### Controller connection attributes ##### **id** (string) _mandatory_ The id of the controller. ##### **name** (string) _ignored_ The name of the controller. ##### **connectionState** (string) _ignored_ CONNECTED or DISCONNECTED ##### **connectionInfo** (string) _ignored_ Details regarding the connection state intended for human consumption. ## Door Action | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | Perform | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/action/[id][urlparameters] | door action | door action | Perform the grant access action on a door denoted by id above with this request. A blocked door mode will result in an Unsupported Request Error. The value of the attribute 'issue' will be "BLOCKED". An offline door will result in an Offline Error ### Door Action object ``` { "action": "GRANT_ACCESS", "door": { "id": "door1", "name": "Entrance door" } } ``` ### Door Action attributes ##### **action** (string) _mandatory_ Must be "GRANT_ACCESS". ##### **door** (object reference) _ignored_ The target door for the action. ## Door Groups | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/doorgroups | | array[door group] | | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/doorgroups | door group | door group | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/doorgroups/[id][urlparameters] | | door group | | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/doorgroups/[id][urlparameters] | door group | door group | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/doorgroups/[id][urlparameters] | | | ### Door Group object ``` { "id": "doorgroup1", "name": "Equipment rooms", "policies": [ { "id": "policy1", "name": "Ground floor - office hours" }, { "id": "policy2", "name": "Ground floor - weekends" } ], "doors": [ { "id": "door1", "name": "Server room" }, { "id": "door2", "name": "HVAC room" } ] } ``` ### Door Group attributes ##### **id** (string) _ignored_ The id of the door group. ##### **name** (string) _mandatory_ The name of the door group. ##### **policies** (array[object reference]) _optional_ The polices that include this door group. ##### **doors** (array[object reference]) _optional_ The doors included in this door group. ## Events | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/events?[parameter](#eventparam)=value&... | | array[event] | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/events/[id][urlparameters] | | event | ### Listing + <a id="eventparam"></a>Parameters + offset - (number) Controls the results starting point by position. + before - (id) Controls the results ending point relative an event. + after - (id) Controls the results starting point relative an event. + limit - (number) This parameter limits the maximum number of events to be retrieved. + mintime - (number) Controls the results ending point by log time in milliseconds since the epoch. + maxtime - (number) Controls the results starting point by log time in milliseconds since the epoch. + token - (id) Retrieve events that involve the token with this id only. + user - (id) Retrieve events that involve the user with this id only. + method - (string) Retrieve events that were caused by a method of a particular type only. + reason - (string list) Retrieve events that are of the reasons provided only. Multiple values may be specified, separated by commas. + door - (id list) Retrieve events that involve the door with these ids only. Multiple values may be specified, separated by commas. + extended - (any value) Turns on the extended version of the request. Responses to requests without this parameter will exclude events, as specified further below, unless specifically included through the reason parameter. All query parameters are optional and provide filtering of the events retrieved. The response is always ordered from newer to older. Parameters "offset", "before" and "after" are mutually exclusive; only one can be used in the same request. The names of the parameters "before" and "after" may be confusing. They refer to the events positions in the results, not on the time line. Examples: If a total of 100 events exist, IDs 1 to 100 where 1 is the oldest and 100 is the newest, then: + limit = 4 will return events 100, 99, 98, and 97; the 4 most recent events. + offset = 2 & limit = 1 will return the event 98; the third most recent event. + before = 99 will return events 100; all events newer than the event with id 99. + after = 99 & limit = 2 will return events 98 and 97; the newest 2 events older than the event with id 99. ### Event object Example 1 ``` { "id": "event4", "command": null, "logTime": 1468577500000, "method": "CARD", "reason": "ACCESS", "info": null, "token": { "id": "token1", "name": "Alice's card" }, "user": { "id": "user1", "name": "Alice Smith" }, "policy": { "id": "policy1", "name": "Ground floor - office hours" }, "door": { "id": "door1", "name": "Entrance door" }, "controller": { "id": "controller1", "name": "Entrance door controller" }, "trigger": null } ``` Example 2 ``` { "id": "event3", "command": null, "logTime": 1468577600000, "method": "REX", "reason": ACCESS, "info": null, "token": null, "user": null, "policy": null, "door": { "id": "door1", "name": "Entrance door" }, "controller": { "id": "controller1", "name": "Entrance door controller" }, "trigger": null } ``` Example 3 ``` { "id": "event2", "command": null, "logTime": 1468577700000, "method": "CARD", "reason": "DENY_UNRECOGNIZED_CARD", "info": "AABBCCDDEE", "token": null, "user": null, "policy": null, "door": { "id": "door1", "name": "Entrance door" }, "controller": { "id": "controller1", "name": "Entrance door controller" }, "trigger": null } ``` Example 4 ``` { "id": "event1", "command": { "id": "command1", "name": "Release entrance door" }, "logTime": 1468577800000, "method": "COMMAND", "reason": "OVERRIDE_CANCELED", "info": null, "token": null, "user": null, "policy": null, "door": { "id": "door1", "name": "Entrance door" }, "controller": { "id": "controller1", "name": "Entrance door controller" }, "trigger": { "id": "trigger1", "name": "Close down" } } ``` ### Event attributes [eventattributes]: #/introduction/events/event-attributes ##### **id** (string) The id of the event. ##### **command** (object reference) Command involved in the event if applicable. ##### **logTime** (number) The time of the event as milliseconds since the epoch. ##### **method** (string) The origin of the event one of API, API_1, API_2, CARD, COMMAND, PIN, REMOTE, REX, SCHEDULE, TRIGGER, URL or UNDEFINED. The value API denotes the method called "Officer" in the Access Manager UI. ##### **reason** (string) The reason for the event. + ACCESS access requested and granted. + ACCESS_UNAUTHORIZED currently unauthorized access requested but granted. + DENY_UNREACHABLE access requested but communication with the controller failed. + DENY_READ_ERROR access requested but we couldn't make sense of the token. + DENY_UNRECOGNIZED_TOKEN access requested but the presented card ID has not been registered. + DENY_AUTHORIZED currently authorized acces+uested but denied. + DENY_UNAUTHORIZED [older events only] access requested but has not been authorized. + DENY_TOKEN_BLOCKED access requested but the token's blocked attribute is true. + DENY_NO_USER access requested but the token is not assigned to user. + DENY_USER_BLOCKED access requested but the token user's blocked attribute is true. + DENY_INVALID_PIN_ONLY only a PIN was entered and it did not match the PIN of any user. + DENY_PIN_MISMATCH access required a pin in addition to a card and it was not entered correctly. + DENY_NO_AUTHORIZATION access requested but the user has no valid authorizations. + DENY_NO_POLICY access requested but the valid authorizations have no policy for the door. + DENY_NO_SCHEDULE access requested but the valid authorization's policies for the door are off schedule. + ALERT_BATTERY a peripheral has indicated that it needs its battery checked. + ALERT_DOOR_OPEN_TOO_LONG the door was left open for too long. + ALERT_DOOR_FORCED_OPEN the door was forced open. + ALERT_CONTROLLER_TAMPER the cover of the controller was removed. + ALERT_JAMMED a peripheral has indicated that it is jammed. + ALERT_RADIO the signal was lost to a wireless peripheral. + ALERT_READER_DISCONNECTED a reader was disconnected. + ALERT_READER_MOVED a reader was physically moved. In addition, when the 'extended' parameter is included in the request: + ALERT_CONTROLLER_DISCONNECTED the connection to the controller was lost. + ALERT_CONTROLLER_CONNECTED the connection to the controller was regained. + ALERT_CONTROLLER_RESET the controller was reset through Access Manager. + COMMAND a command was issued. + COMMAND_DONE a command finished successfully. + COMMAND_FAILED a command finished unsuccessfully. + CONTROLLER_RESTARTED the controller was restarted through Access Manager. + DENY_DOOR_BLOCKED access requested through a reader was denied because the door was blocked. + DOOR_CLOSED the door was closed. + DOOR_OPENED the door was opened. + OVERRIDE_TO_DOUBLE_LOCKED the lock mode was overridden to double locked state. + OVERRIDE_TO_LOCKED the lock mode was overridden to locked state. + OVERRIDE_TO_UNLOCKED the lock mode was overridden to unlocked state. + OVERRIDE_CANCELED lock mode overridden was canceled. + STATE_DOUBLE_LOCK the door entered the double locked state. + STATE_LOCK the door entered the locked state. + STATE_UNLOCK the door entered the unlocked state. + TRIGGER_DENIED_CREDENTIAL trigger denied because the required credentials were not presented. + TRIGGER_DENIED_DEVICE_BLOCKED trigger denied because the device was blocked. + TRIGGER_DENIED_DOOR trigger denied because the door requirement of the trigger was not fulfilled. + TRIGGER_DENIED_INVALID_PIN_ONLY trigger denied because only a PIN was entered and it did not match the PIN of any user. + TRIGGER_DENIED_NO_USER trigger denied because the device has no user user. + TRIGGER_DENIED_PIN_MISMATCH trigger denied by card+PIN authentication because the entered PIN is not the user's. + TRIGGER_DENIED_ROLE trigger denied because the role requirement of the trigger was not fulfilled. + TRIGGER_DENIED_SCHEDULE trigger denied because the trigger was inactive by schedule. + TRIGGER_DENIED_UNRECOGNIZED_TOKEN trigger denied by card authentication because the card is not recognized. + TRIGGER_DENIED_USER_BLOCKED trigger denied because the user is blocked. + TRIGGER_GRANTED trigger granted and its commands issued. Note that whether an event will occur for a particular reason will occur is subject to controller and peripheral types and configurations. ##### **info** (string) Holds the card ID as read by the controller if reason is DENY_UNRECOGNIZED_TOKEN. ##### **token** (array[object reference]) Token involved in the event if applicable. ##### **user** (array[object reference]) User involved in the event if applicable. ##### **policy** (array[object reference]) Policy involved in the event if applicable. ##### **door** (array[object reference]) Door involved in the event if applicable. ##### **controller** (array[object reference]) Controller involved in the event if applicable. ##### **trigger** (array[object reference]) Trigger involved in the event if applicable. ## Hubs | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/hubs | | array[hub] | | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/hubs | hub | hub | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/hubs/[id][urlparameters] | | hub | | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/hubs/[id][urlparameters] | hub | hub | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/hubs/[id][urlparameters] | | | ### Hub object ``` { "id": "hub1", "name": "Entrance hub", "description": "The hub connected to the entrance controller", "type": "INTEGO""ipAddress": "192.168.1.43""deviceAddress": "0x00000100", "controller": { "id": "controller1", "name": "Entrance controller" }, "doors": [ { door: { "id": "door2", "name": "Inner entrance door 2" }, lockId: "0x00000200", monitorId: "00E8E3F" }, { door: { "id": "door3", "name": "Inner entrance door 3" }, lockId: "0x00000300", monitorId: "00F24KM" } ] } ``` ### Hub attributes ##### **id** (string) _ignored_ The id of the hub. ##### **name** (string) _mandatory_ The name of the hub. ##### **description** (string) _optional_ The description of the hub. ##### **type** (string) _mandatory_ One of APERIO and INTEGO. ##### **ipAddress** (string) _optional_ Hub IP address, needed for INTEGO. ##### **deviceAddress** (string) _optional_ Hub device address, needed for INTEGO. ##### **controller** (object reference) _ignored_ The controller to which the hub is allocated. ##### **doors** (array[hub door reference]) _optional_ The doors allocated to this hub. ### Hub Door Reference attributes ##### **door** (object reference) _mandatory_ The door. ##### **lockId** (string) _mandatory_ The lock id (a.k.a. Device address). ##### **monitorId** (string) _mandatory_ The monitor id (a.k.a. Phi string). ## Notifications | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/notifications | | array[notification] | | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/notifications | notification | notification | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/notifications/[id][urlparameters] | | notification | | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/notifications/[id][urlparameters] | notification | notification | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/notifications/[id][urlparameters] | | | ### Notification object ``` { "id": "notification1", "name": "Watch for Alice", "description": "Alice Smith is in the building.", "minMillisBetween": 60000, "reasons": [ ACCESS ], "recipientsSms": [ +1234567890 ], "recipientsEmail": [ "watch@dog.com" ], "recipientsHttp": [ "https://u:p@watch.dog.com" ], "onlyDuring": { "id": "schedule1", "name": "Office hours" }, "unlessDuring": { "id": "schedule2", "name": "Open house hours" }, "onlyControllers": [ { "id": "controller1", "name": "Entrance controller" } ], "onlyTokens": [ { "id": "token1", "name": "Alice's card" } ], "onlyDoors": { "doors": [ { "id": "door1", "name": "Entrance" } ], "doorsGroups": [ { "id": "doorgroup1", "name": "Back doors" } ] }, "onlyMethods": [ "CARD" ], "onlyUsers": { "users": [ { "id": "user1", "name": "Alice Smith" } ], "authorizations": [ { "id": "authorization1", "name": "Catering" } ] } } ``` ### Notification attributes ##### **id** (string) _ignored_ The id of the notification. ##### **name** (string) _mandatory_ The name of the notification. ##### **description** (string) _optional_ The description of the notification. ##### **minMillisBetween** (number) _mandatory_ Least time in milli seconds between notification deliveries. Deliveries are skipped to comply. ##### **reasons** (array[string]) _mandatory_ Only consider events with one of these reason attribute values. Possible values are documented in the [Event attributes][eventattributes] section. ##### **recipientsSms** (array[string]) _optional_ List of international format phone numbers to deliver to, e.g. `["+1234567890"]`. Defaults to none. ##### **recipientsEmail** (array[string]) _optional_ List of email addresses to deliver to, e.g. `["watch@dog.com"]`. Defaults to none. ##### **recipientsHttp** (array[string]) _optional_ List of HTTP (or HTTPS) listeners to deliver to, e.g. `["https://u:p@watch.dog.com"]`. Defaults to none. ##### **onlyDuring** (object reference) _optional_ Only consider events that occur when this schedule was active. ##### **unlessDuring** (object reference) _optional_ Only consider events that did not occur when this schedule was active. ##### **onlyControllers** (array[object reference]) _optional_ Only consider events with one of these controller attribute values. ##### **onlyTokens** (array[object reference]) _optional_ Only consider events with one of these token attribute values. ##### **onlyDoors** (array[object reference]) _optional_ Only consider events with a door attribute value that is listed or contained in at least one of the door groups. ##### **onlyMethods** (array[string]) _optional_ Only consider events with one of these method attribute values. Possible values are documented in the [Event attributes][eventattributes] section. ##### **onlyUsers** (array[object reference]) _optional_ Only consider events with a user attribute value that is listed or contained in at least one of the authorizations. ## O3C Registration | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/controllers/[id][urlparameters]/o3c | o3c registration | | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/o3c/[id][urlparameters]/o3c | | | For managing the registration of controllers connected via the One-Click Connection Component (O3C). Creating the resource registers the controller with O3C, and deleting the resource unregisters the controller. This resource is immutable and there can be only be one per controller. To change the registration, the existing resource must be deleted before creating a new one with the new details. ### O3C Registration object ``` { "mac": "556677889900", "oak": "yuiwe87yuqqoiee" } ``` ### O3C Registration attributes ##### **mac** (string) _mandatory_ The MAC of the controller. ##### **oak** (string) _mandatory_ The OAK for the controller. ## Policies | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/policies | | array[policy] | | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/policies | policy | policy | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/policies/[id][urlparameters] | | policy | | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/policies/[id][urlparameters] | policy | policy | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/policies/[id][urlparameters] | | | ### Policy object "Policies" are known as "Privileges" in the Access Manager UI. ``` { "id": "policy1", "name": "General access", "description": "Ground floor during office hours", "credential": "CARD", "schedule": { "id": "schedule1", "name": "Office hours" }, "authorizations": [ { "id": "authorization1", "name": "Janitor" }, { "id": "authorization2", "name": "Manager" } ], "doors": [ { "id": "door1", "name": "Entrance" }, { "id": "door2", "name": "Server room" } ], "doorsInside": [ ], "doorsOutside": [ ], "doorGroups": [ { "id": "doorgroup1", "name": "Ground floor" }, { "id": "doorgroup2", "name": "Equipment rooms" } ] } ``` ### Policy attributes ##### **id** (string) _ignored_ The id of the policy. ##### **name** (string) _mandatory_ The name of the policy. ##### **description** (string) _optional_ A description of the policy. ##### **credential** (string) _mandatory_ The type of credential that may be used to gain access. One of + CARD: Only a card is required. + CARD_PIN: Both a card and a PIN is required. + PIN: Only a PIN is required. + REMOTE: Telcred Remote is required. + API_1 and API_2: An API request to access is required. See Request Access by User ID. ##### **schedule** (array[object reference]) _optional_ A schedule defining time periods where the policy is effective. None (null) means always. ##### **authorizations** (array[object reference]) _optional_ The list of authorizations that has this policy. ##### **doors** (array[object reference]) _optional_ The list of doors for which this policy applies to access from both inside and outside. ##### **doorsInside** (array[object reference]) _optional_ The list of doors for which this policy applies to access from the inside. ##### **doorsOutside** (array[object reference]) _optional_ The list of doors for which this policy applies to access from the outside. ##### **doorGroups** (array[object reference]) _optional_ The list of door groups for which this policy applies to access from both inside and outside. A door is only included once, either in doors, doorsInside, or doorsOutside. In requests, multiple inclusions of a door in doors, doorsInside, and doorsOutside, are resolved additively. For example + doors: [a, b], + doorsInside: [b , c], + doorsOutside: [c, d] is equivalent to + doors: [a, b, c], + doorsInside: [], + doorsOutside: [d]. When a request only updates some of these values they are first replaced completely, where after they are combined with the unchanged values. For example where + doors: [a], + doorsInside: [b], + doorsOutside: [c] An update with only doorsInside: [a], results in + doors: [a], + doorsInside: [], + doorsOutside: [c]. Or an update performed with only doors: [c], results in + doors: [c], + doorsInside: [b], + doorsOutside: []. ## Request Access | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | By token CID | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/access/doors/[id][urlparameters]/tokens | access request | access request | | By token ID | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/access/doors/[id][urlparameters]/tokens/[id][urlparameters] | access request | access request | | By user PIN | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/access/doors/[id][urlparameters]/users | access request | access request | | By user ID | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/access/doors/[id][urlparameters]/users/[id][urlparameters] | access request | access request | ### Access Request object ``` { "authorization": { "id": "authorization1", "name": "IT Technician" }, "cid": "456678768", "credentials": [ "CARD", "CARD_PIN" ], "door": { "id": "door1", "name": "Entrance door" }, "granted": false, "pin": "1111", "policy": { "id": "policy1", "name": "Ground floor - office hours" }, "reason": "DENY_PIN_MISMATCH", "token": { "id": "token1", "name": "Alice's card" }, "user": { "id": "user1", "name": "Alice Smith" } } ``` In the request, most of the attributes are ignored. If there are no errors, the response will have status code 200 and document the outcome of the request to access. Note that this will be the case regardless of whether access was granted or denied. ##### By Token CID Request access for a token specified by CID. In the request the attribute "cid" is mandatory and the attribute "pin" is optional. The remaining attributes are only relevant to the response. ##### By Token ID Request access for a token specified by ID. In the request the attribute "pin" is optional and the remaining attributes are only relevant to the response. ##### By User PIN Request access for a user specified by PIN. If the PIN matches several users access will be granted unless denied for all. In the request the attribute "pin" is mandatory and the remaining attributes are only relevant to the response. ##### By User ID Request access for a user specified by ID. Only policies that allow credentials API_1 or API_2 can match this request. In the request the attribute "credentials" is mandatory. The value may be a list of either "API_1", or "API_2", or both. The remaining attributes are only relevant to the response. ### Access Request attributes ##### **authorization** (object reference) _ignored_ One (of possibly several) matching authorizations; or null if none. ##### **cid** (string) _mandatory or optional_ The token CID. ##### **credentials** (array[string]) _ignored_ A list of the considered credentials; policies must match at least one. One or both of CARD and CARD_PIN. ##### **door** (object reference) _ignored_ The door for which access is requested. ##### **granted** (boolean) _ignored_ Set to true if access was granted, false otherwise. ##### **pin** (string) _mandatory or optional_ The PIN used if any; otherwise null. ##### **policy** (object reference) _ignored_ One (of possibly several) matching policies; or null if none. ##### **reason** (string) _ignored_ The reason for a denied request. See events for a list of possible values. ##### **token** (object reference) _ignored_ The token that matches the CID, or null if none. ##### **user** (object reference) _ignored_ The user of the token that matches the CID, or null if none. ## Schedules | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/schedules | | array[schedule] | | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/schedules | schedule | schedule | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/schedules/[id][urlparameters] | | schedule | | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/schedules/[id][urlparameters] | schedule | schedule | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/schedules/[id][urlparameters] | | | ### Schedule object ``` { "id": "schedule1", "name": "Office hours", "description": "All weekdays less Xmas and Swedish midsummer 2017", "include": { "once": [ ], "weekly": [ { "from": "08:00:00", "to": "17:59:59", "days": [ "MO", "TU", "WE", "TH", "FR" ], "start": "2017-01-01", "end": "2029-12-31" } ], "yearly": [ ] }"exclude": { "once": [ { "from": "2017-06-23T00:00:00", "to": "2017-06-25T23:59:59" } ], "weekly": [ ], "yearly": [ { "from": "--12-24T00:00:00", "to": "--12-26T23:59:59" } ] }, "policies": [ { "id": "policy2", "name": "Ground floor - weekends" } ], "doors": [ { "id": "door1", "name": "Entrance door" } ] } ``` The schedule defines a set of time periods through the attributes include and exclude according to these rules: + Only time periods covered by include attribute are in the set. + Time periods covered by the exclude attribute are not in the set, regardless. The internal structure of attributes include and exclude are identical: A set of once items, a set of weekly items, and a set of yearly items. The coverage of each attribute is the union of the coverage of the attributes items. Each Once item covers a single time interval. Attributes: + from: The first second to be included on the format yyyy-MM-ddTHH:mm:ss, e.g. `2017-11-23T00:00:00`. + to: The last second to be included in the interval denoted as above. Example: `{"from": "2017-12-31T00:00:00", "to": "2017-12-31T23:59:59"}` is the whole day, 2017-12-31. Each Weekly item covers from one time of day to a second time of day, one or more weekdays, recurring weekly but limited by a first and a last date. Attributes: + from: The first second to be included on a daily basis in the format HH:mm:ss, e.g. `13:00:00`. + to: The last second to be included on a daily basis denoted as above. + days: A list of the covered weekdays denoted as MO, TU, WE, TH, FR, SA, and SU. + start: The first day of coverage as a date, in the format yyyy-MM-dd, e.g. `2017-01-01`. + end: The last day of coverage as a date, denoted as above. E.g. `{"from": "00:00:00", "to": "23:59:59", "days": ["SU"], "start": "2017-01-01", "end": "2017-01-08"}` is all of Sunday 2017-01-01 and all of Sunday 2017-01-08. Each Yearly item covers one time interval recurring yearly. Attributes: + from: The first second to be included on a yearly basis, in the format --MM-ddTHH:mm:ss, e.g. `--11-23T00:00:00`. + to: The last second to be included on a yearly basis, denoted as above. E.g. `{"from": "--12-01T00:00:00", "to": "--12-31T23:59:59"}` is all of December every year. The following notation is used for the formats above: + yyyy = four-digit year + MM = two-digit month (01=January, etc.) + dd = two-digit day of month (01 through 31) + HH = two digits of hour (00 through 23; weekly, see below) + mm = two digits of minute (00 through 59) + ss = two digits of second (00 through 59) Note that time intervals are closed, e.g. from 12:00:00 to 12:00:01 is two seconds, and from 2017-01-01 to 2017-01-02 is two days as well as is from --01-01 to --01-02. ### Schedule attributes ##### **id** (string) _ignored_ The id of the schedule. ##### **name** (string) _mandatory_ The name of the schedule. ##### **description** (string) _optional_ The description of the schedule. ##### **include** (schedule time set) _optional_ Time periods that are in the set unless excluded. ##### **exclude** (schedule time set) _optional_ Time periods that are not in the set although included. ##### **policies** (array [object reference]) _ignored_ All policies using this schedule. ##### **doors** (array [object reference]) _ignored_ All doors using this schedule. ### Schedule Time Set attributes ##### **once** (array [schedule time once]) _optional_ A single time interval. ##### **weekly** (array [schedule time weekly]) _optional_ Time interval recurring weekly. ##### **yearly** (array [schedule time yearly]) _optional_ Time interval recurring yearly. ### Schedule Time Once attributes ##### **from** (string) _mandatory_ The first second to be included on the format yyyy-MM-ddTHH:mm:ss. ##### **to** (string) _mandatory_ The last second to be included on the format yyyy-MM-ddTHH:mm:ss. ### Schedule Time Weekly attributes ##### **from** (string) _mandatory_ The first second to be included on a daily basis in the format HH:mm:ss, e.g. `13:00:00`. ##### **to** (string) _mandatory_ The last second to be included on a daily basis in the format HH:mm:ss, e.g. `13:00:00` ##### **days** (array[string]) _mandatory_ A list of the included weekdays denoted as MO, TU, WE, TH, FR, SA, and SU. E.g. `["SA","SU"]`. ##### **start** (string) _mandatory_ The first day to be included as a date, in the format yyyy-MM-dd, e.g. `2017-01-01`. ##### **end** (string) _mandatory_ The last day to be included as a date, in the format yyyy-MM-dd, e.g. `2017-01-01`. ### Schedule Time Yearly attributes ##### **from** (string) _mandatory_ The first second to be included on a yearly basis, in the format --MM-ddTHH:mm:ss. ##### **to** (string) _mandatory_ The last second to be included on a yearly basis, in the format --MM-ddTHH:mm:ss ## Tokens "Tokens" are known as "Devices" in the Access Manager UI. | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/tokens | | array[token] | | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/tokens | token | token | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/tokens/[id][urlparameters] | | token | | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/tokens/[id][urlparameters] | token | token | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/tokens/[id][urlparameters] | | | ### Token object ``` { "id": "token5", "name": "Cindy's card", "description": "White with red print.", "type": "CID", "cid": "AABBCCDDEE", "blocked": false, "user": { "id": "user4", "name": "Cindy Smith" }, "userFrom": null, "userTo": "2017-06-25T17:30:00" } ``` ### Token attributes ##### **id** (string) _ignored_ The id of the token. ##### **name** (string) _mandatory_ The name of the token. ##### **description** (string) _optional_ A description of the token. ##### **type** (string) _mandatory_ One of + CID the token is a card and will be identified by its raw id. + CNR the token is a card and will be identified by its number derived from the raw id. + MOBILE the token is a smart phone. ##### **cid** (string) _optional_ The card ID or card number (if the token is a card). ##### **blocked** (boolean) _optional_ true if the token is blocked. Defaults to false. ##### **user** (array[object reference]) _optional_ The user this token is bound to. ##### **userFrom** (string) _optional_ The first second of the binding to the user, on the format yyyy-MM-ddTHH:mm:ss, e.g. `2017-11-23T00:00:00`, in the time zone of the controller. Defaults to unlimited. ##### **userTo** (string) _optional_ The last second of the binding to the user denoted as above. E.g. `{"user":{"id": "user4"}, "userFrom": "2017-12-31T00:00:00", "userTo": "2017-12-31T23:59:59"}` will bind the token to user id user4 for the whole day, 2017-12-31, in the time zone of the controller. Defaults to unlimited. ## Users "Users" refers to people with tokens which can open doors. This does not include administrators of the system. | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/users | | array[user] | | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/users | user | user | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/users/[id][urlparameters] | | user | | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/users/[id][urlparameters] | user | user | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/users/[id][urlparameters] | | | ### User object ``` { "id": "user4", "name": "Cindy Jones", "pin": "12345", "blocked": true, "tokens": [ { "id": "token1", "name": "Card 01""userFrom": null, "userTo": "2017-06-25T17:30:00" }, { "id": "token2", "name": "Cindy's phone""userFrom": "2017-06-24T08:15:00", "userTo": "2017-06-25T17:30:00" } ], "authorizations": [ { "id": "authorization1", "name": "Janitor" }, { "id": "authorization2", "name": "Manager" } ] } ``` ### User attributes ##### **id** (string) _ignored_ The id of the user. ##### **name** (string) _mandatory_ The name of the user. ##### **pin** (string) _optional_ The PIN of the user. Limited to at most 9 characters. ##### **blocked** (boolean) _optional_ true if the user is blocked. Defaults to false. ##### **tokens** (array[token binding]) _optional_ Tokens bound to the user. ##### **authorizations** (array[object reference]) _optional_ The authorizations of this user. ### Token binding attributes ##### **id** (string) _mandatory_ The id of the token. ##### **name** (string) _ignored_ The name of the token. ##### **userFrom** (string) _optional_ The first second of the binding to the user. See token. ##### **userTo** (string) _optional_ The last second of the binding to the user. See token. ## Visits | Action | Method | URL | Request body | Response body | |-----|-----|----|-----|----| | List | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/visits | | array[visit] | | Create | POST | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/visits | visit | visit | | Retrieve | GET | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/visits/[id][urlparameters] | | visit | | Update | PUT | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/visits/[id][urlparameters] | visit | visit | | Delete | DELETE | /v2/sys/[sys][urlparameters]/org/[org][urlparameters]/visits/[id][urlparameters] | | | ### Visit object ``` { "id": "visit1", "name": "May marketing event", "description": "Open house", "credentials": [ "PIN", "URL" ], "validFrom": "2017-06-25T18:30:00", "validTo": "2017-06-25T20:00:00", "pin": "1066", "url": "https://access.manager.com/welcome/1/37/1fhn1po", "schedule": { "id": "schedule1", "name": "Office hours" }, "doors": [ { "id": "door1", "name": "Entrance" } ] } ``` ### Visit attributes ##### **id** (string) _ignored_ The id of the visit. ##### **name** (string) _mandatory_ The name of the visit. ##### **description** (string) _optional_ The description of the visit. ##### **credential** (array[string]) (string) _mandatory_ The type of credential used to gain access. One or both of PIN and URL. E.g. `["PIN", "URL"]`. ##### **validFrom** (string) _optional_ The first second of validity on the format yyyy-MM-ddTHH:mm:ss, e.g. `2017-11-23T00:00:00`, in the time zone of the controller. Defaults to unlimited. ##### **validTo** (string) _optional_ The last second of validity on the format yyyy-MM-ddTHH:mm:ss, e.g. `2017-11-23T00:00:00`, in the time zone of the controller. Defaults to unlimited. ##### **schedule** (object reference) _optional_ A schedule defining time periods when the visit applies. None (null) means always. ##### **doors** (array[object reference]) _optional_ The list of doors for which this visit applies. ## Error Responses Status code 400 is used for all error responses. The body of the response will be a JSON object (application/json) with the following attributes. ##### **type** (string) One of MISSING, CONFLICT,... as documented below. ##### **issue** (string) A parameter intended for programmatic consumption. ##### **info** (string) A message intended for human consumption. #### Invalid id Parameter Error An error with type set to MISSING is returned if no object of the requested type can be found for the id parameter. The attribute 'issue' will supply the id. ``` { "type": "MISSING", "issue": "user2", "info": "There exists no user with the id user2." } ``` #### Invalid Object Reference Error An error with type set to MISSING is returned if one or more of the specified object references do not exist. In this case the attribute 'issue' will hold one of the missing ids. ``` { "type": "MISSING", "issue": "user2", "info": "There exists no user with the id user2." } ``` #### Name Conflict Error An error with type set to CONFLICT is returned if a name is already in use. In this case the attribute 'issue' will hold the conflicting name. ``` { "type": "CONFLICT", "issue": "IT technician", "info": "There already exists an authorization with the name IT technician." } ``` #### Unauthorized Access Error An error with type set to UNAUTHORIZED is returned if the credentials supplied through HTTP Basic Auth do not match an officer with administration privileges. The attribute issue will hold the username part of the credentials regardless of whether the issue is with the username or with the password. ``` { "type": "UNAUTHORIZED", "issue": "BadCop" "info": "Sign in failed for 'BadCop'." } ``` #### Inapplicable Method Error An error with type set to METHOD is returned if the method of the request (GET/PUT/...) is not applicable to the resource given by the path of the request. ``` { "type": "METHOD", "issue": null "info": "The method (GET/PUT/POST/DELETE) is not defined for this resource." } ``` #### Unknown Path Error An error with type set to PATH is returned if the path of the request is not recognized. ``` { "type": "PATH", "issue": null "info": "This resource is not defined." } ``` #### Unsupported Request Error An error with type set to UNSUPPORTED is returned if the request cannot be fulfilled due to a dynamic or static constraint. ``` { "type": "UNSUPPORTED", "issue": "BLOCKED" "info": "Access cannot be granted because this door is blocked." } ``` #### Offline Error An error with type set to CONNECTION is returned if the request cannot be fulfilled due a door/controller being offline. The attribute 'issue' will hold the id of the controller. ``` { "type": "CONNECTION", "issue": "controller1", "info": "The controller is offline." } ``` #### Value Error An error with type set to VALUE is returned if the values provided for any of the attributes in a request are invalid. The attribute 'issue' will hold the invalid value. ``` { "type": "VALUE", "issue": "WIEGAND_TRIPLE_LED", "info": "'WIEGAND_TRIPLE_LED' is not recognized as a valid type for a reader." } ``` #### O3C Registration Error An error with type set to O3C is returned if the details provided for the registration are incorrect or if a registration for this controller already exists. ``` { "type": "O3C", "issue": "controller1", "info": "There already exists a registration for the controller with id controller1" } ```