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

FORMAT: 1A HOST: https://access.telcred.com # v2 Telcred Access Manager Admin API #### The Admin API This API allows you to administer access rights in Telcred Access Manager. Before you start, you need to have at least one System and one Organization (both identified by IDs), and one Officer with administrator capacity (identified by username) defined. The system id is provided by Telcred. The Telcred Access Manager Owner API can be used to find the organization id. See https://v2accessmanagerowner.docs.apiary.io/# The documentation of the requests and responses body format, in the spirit of REST APIs and for the sake of readability, is done by example, and not only the values but also the order of the properties may and will vary between requests. #### 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. # Group Requests The resources Authorizations, Tokens, and Policies are commonly called Roles, Devices and Privileges in the Access Manager. ## Authorizations [/v2/sys/{sys}/org/{org}/authorizations] + Parameters + sys - The id of the system. + org - The id of the organization. ### List All Authorizations [GET] This request will retrieve a list of all defined authorizations. If there are no authorizations the list will be empty. The attribute 'type' can be either ROLE or ASSIGNMENT. The validity period is specified as a half-open interval in milliseconds from the Unix epoch. The attribute validFrom is the start of the interval inclusive. The attribute validTo is the end of interval exclusive. + Response 200 (application/json) [ { "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": "Alice Smith" }, { "id": "user2", "name": "Bob Smith" } ] } ] ### Create a New Authorization [POST] Create new authorizations using this request. The request takes an object containing a name, the authorization type (ROLE or ASSIGNMENT), a validity period, a list of policies and a list of users. Mandatory attributes: name, type, validFrom, validTo Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned if one or more of the specified policies and/or users do not exist. In this case the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "name": "IT technician", "type": "ROLE", "validFrom": 0, "validTo": 3155760000000, "policies": [ { "id": "policy1" }, { "id": "policy2" } ], "users": [ { "id": "user1", }, { "id": "user2", } ] } + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "IT technician", "info": "There already exists an authorization with the name IT technician." } + Response 400 (application/json) { "type": "MISSING", "issue": "user2", "info": "There exists no user with the id user2." } ## Authorization by ID [/v2/sys/{sys}/org/{org}/authorizations/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined authorization that will be the target of the operation. ### Retrieve an Authorization [GET] Retrieve the current definition of an authorization with this request. The response will include the authorization name, type, validity period, a list of policies, and a list of users. Status code 400 and an explanatory object of type MISSING is returned if no authorization can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "MISSING", "issue": "authorization2", "info": "There exists no authorization with the id authorization2." } ### Update an Authorization [PUT] Update the definition of an authorization with this request. It takes an authorization object, same as POST, and replaces all values completely. Attributes may be omitted from the request in which case their values will not be affected. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned if one or more of the specified policies and/or users do not exist. In this case the attribute 'issue' will hold one of the missing ids. Status code 400 and an explanatory object of type MISSING is returned if no authorization can be found for the target id. The attribute 'issue' will supply the id. + Request (application/json) { "name": "IT technician", "type": "ROLE", "validFrom":0, "validTo":3155760000000, "policies": [ { "id": "policy1" }, { "id": "policy2" } ], "users": [ { "id": "user1", }, { "id": "user2", } ] } + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "IT technician", "info": "There already exists an authorization with the name IT technician." } + Response 400 (application/json) { "type": "MISSING", "issue": "user2", "info": "There exists no user with the id user2." } + Response 400 (application/json) { "type": "MISSING", "issue": "authorization1", "info": "There exists no authorization with the id authorization1." } ### Delete an Authorization [DELETE] Use this request to irrevocably delete an authorization. Status code 400 and an explanatory object of the type MISSING is returned if no authorization can be found for the target id. The attribute 'issue' will supply the id. + Response 200 + Response 400 (application/json) { "type": "MISSING", "issue": "authorization1", "info": "There exists no authorization with the id authorization1." } ## Users [/v2/sys/{sys}/org/{org}/users] + Parameters + sys - The id of the system. + org - The id of the organization. ### List All Users [GET] This request will retrieve a list of all defined users. If there are no users the list will be empty. Note: 'users' refers to people with tokens which can open doors. It does not include administrators of the system. + Response 200 (application/json) [ { "id": "user1", "name": "Alice Smith", "pin": "12345", "blocked": false, "tokens": [ { "id": "token1", "name": "Card 01", "userFrom": null, "userTo": "2017-06-25T17:30:00" }, { "id": "token2", "name": "Alice's phone", "userFrom": null, "userTo": null } ], "authorizations": [ { "id": "authorization1", "name": "Janitor" }, { "id": "authorization2", "name": "IT Technician" } ] } ] ### Create a New User [POST] Create new users with this request. It takes an object containing a name, a PIN, whether the user shall be blocked, a list of tokens, and a list of authorizations for the new user. These lists may be empty or omitted entirely. Mandatory attributes: name. The blocked attribute defaults to false. The value of the pin attribute must be numeric and is limited to at most 9 characters. Each token may optionally set the userFrom and userTo attributes (see section on Token). Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned if one or more of the specified tokens or authorizations do not exist. In this case the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "name": "Cindy Smith", "pin": "12345", "blocked": false, "tokens": [ { "id": "token1", "userFrom": null, "userTo": "2017-06-25T17:30:00" }, { "id": "token2" } ], "authorizations": [ { "id": "authorization1" }, { "id": "authorization2" } ] } + Response 200 (application/json) { "id": "user4", "name": "Cindy Smith", "pin": "12345", "blocked": false, "tokens": [ { "id": "1", "name": "Card 01", "userFrom": null, "userTo": "2017-06-25T17:30:00" }, { "id": "token2", "name": "Cindy's phone" "userFrom": null, "userTo": null } ], "authorizations": [ { "id": "authorization1", "name": "Janitor" }, { "id": "authorization2", "name": "Manager" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Cindy Smith", "info": "There already exists a user with the name Cindy Smith." } + Response 400 (application/json) { "type": "MISSING", "issue": "authorization2" "info": "There exists no authorization with the id authorization2." } ## User by ID [/v2/sys/{sys}/org/{org}/users/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined user that will be the target of the operation. ### Retrieve a User [GET] Retrieve the current definition of a user with this request. The response will include a list of tokens belonging to the user as well as a list of authorizations that the user is a holder of. Status code 400 and an explanatory object of type MISSING is returned if no user can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "id": "user4", "name": "Cindy Smith", "pin": "12345", "blocked": false, "tokens": [ { "id": "token1", "name": "Card 01" "userFrom": null, "userTo": "2017-06-25T17:30:00" }, { "id": "token2", "name": "Cindy's phone" "userFrom": null, "userTo": null } ], "authorizations": [ { "id": "authorization1", "name": "Janitor" }, { "id": "authorization2", "name": "Manager" } ] } + Response 400 (application/json) { "type": "MISSING", "issue": "user4", "info": "There exists no user with the id user4." } ### Update a User [PUT] Update the definition of a user with this request. It takes a user object, same as POST, and replaces all values completely. This includes the lists of tokens and authorizations for the user. The value of the pin attribute must be numeric and is limited to at most 9 characters. Attributes may be omitted from the request in which case their values will not be affected. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use for a different user. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned for either of three reasons: + No user can be found for the target id. + One or more of the specified tokens do not exist. + One or more of the specified authorizations do not exist. In this case, the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "name": "Cindy Jones", "pin": "12345", "blocked": true, "tokens": [ { "id": "token1" }, { "id": "token2" "userFrom": "2017-06-24T08:15:00", "userTo": "2017-06-25T17:30:00" } ], "authorizations": [ { "id": "authorization1" }, { "id": "authorization2" } ] } + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Cindy Jones", "info": "There already exists a user with the name Cindy Jones." } + Response 400 (application/json) { "type": "MISSING", "issue": "user4", "info": "There exists no user with the id user4." } ### Delete a User [DELETE] Use this request to irrevocably delete a user. Status code 400 and an explanatory object of the type MISSING is returned if no user can be found for the target id. The attribute 'issue' will supply the id. + Response 200 + Response 400 (application/json) { "type": "MISSING", "issue": "user4", "info": "There exists no user with the id user4." } ## Tokens [/v2/sys/{sys}/org/{org}/tokens] + Parameters + sys - The id of the system. + org - The id of the organization. ### List All Tokens [GET] This request will retrieve a list of all tokens. If there are no tokens, the list will be empty. + Response 200 (application/json) [ { "id": "token1", "name": "Card 01", "description": "White with red print.", "type": "CID", "cid": "AABBCCDDEE", "blocked": false, "user": { "id": "user1", "name": "Alice Smith" }, "userFrom": null, "userTo": "2017-06-25T17:30:00" } ] ### Create a New Token [POST] Create new tokens using this request. It takes an object containing a name, a description, a type ('CID', 'CNR', or 'MOBILE'), the card id/nr if the token is a card, whether the token shall be blocked, and the binding to a user. Attributes userFrom and userTo specify the time interval under which the binding to the user is in effect. + userFrom: The first second to be included, on the format yyyy-MM-ddTHH:mm:ss, e.g. 2017-11-23T00:00:00, in the timezone of the controller. + userTo: The last second to be included in the interval denoted as above. Example: {"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 timezone of the controller. Mandatory attributes: name, type. The blocked attribute defaults to false. UserFrom and UserTo both default to null, which represents infinite negative and infinite positive time respectively. Status code 400 and an explanatory object of the type CONFLICT is returned if the name or the cid value is in use. In this case the attribute 'issue' will hold the cid value. Status code 400 and an explanatory object of the type MISSING is returned if the specified user does not exist. In this case the attribute 'issue' will hold the missing id. + Request (application/json) { "name": "Cindy's card", "description": "White with red print.", "type": "CID", "cid": "AABBCCDDEE", "blocked": false, "user": { "id": "user4" }, "userFrom": null, "userTo": "2017-06-25T17:30:00" } + Response 200 (application/json) { "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" } + Response 400 (application/json) { "type": "CONFLICT", "issue": "AABBCCDDEE" "info": "The CID AABBCCDDEE is in use." } + Response 400 (application/json) { "type": "MISSING", "issue": "user4" "info": "There exists no user with the id user4." } ## Token by ID [/v2/sys/{sys}/org/{org}/tokens/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined token that will be the target of the operation. ### Retrieve a Token [GET] Retrieve the current definition of a token with this request. Status code 400 and an explanatory object of type MISSING is returned if no token can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "id": "token5", "name": "Cindy's card", "description": "FWhite with red print.", "type": "CID", "cid": "AABBCCDDEE", "blocked": false, "user": { "id": "user4", "name": "Cindy Smith" }, "userFrom": null, "userTo": "2017-06-25T17:30:00" } + Response 400 (application/json) { "type": "MISSING", "issue": "token5", "info": "There exists no token with the id token5." } ### Update a Token [PUT] Update the definition of a token with this request. It takes a token object, same as POST, and replaces all values completely. Attributes may be omitted from the request in which case their values will not be affected. Status code 400 and an explanatory object of the type CONFLICT is returned if the name or the cid is in use for a different token. In this case the attribute 'issue' will hold the conflicting name or cid value. Status code 400 and an explanatory object of the type MISSING is returned for either of two reasons: + No token can be found for the target id. + The specified user does not exist. In this case the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "name": "Alice's card", "description": "Formerly Cindy's card", "type": "CID", "cid": "AABBCCDDEE", "blocked": true, "user": { "id": "user1" }, "userFrom": null, "userTo": "2017-06-25T17:30:00" } + Response 200 (application/json) { "id": "token5", "name": "Alice's card", "description": "Formerly Cindy's card", "type": "CID", "cid": "AABBCCDDEE", "blocked": true, "user": { "id": "user1" "name": "Alice Smith" }, "userFrom": null, "userTo": "2017-06-25T17:30:00" } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Alice's card", "info": "There already exists a token with the name Alice's card." } + Response 400 (application/json) { "type": "MISSING", "issue": "token5", "info": "There exists no token with the id token5." } ### Delete a Token [DELETE] Use this request to irrevocably delete a token. Status code 400 and an explanatory object of type MISSING is returned if no token can be found for the target id. The attribute 'issue' will supply the id. + Response 200 + Response 400 (application/json) { "type": "MISSING", "issue": "token5", "info": "There exists no token with the id token5." } ## Policies [/v2/sys/{sys}/org/{org}/policies] + Parameters + sys - The id of the system. + org - The id of the organization. ### List All Policies [GET] This request will retrieve a list of all policies. If there are no policies, the list will be empty. A policy contains an attribute specifying which credential is used to gain access, and a schedule. The response also contains lists for all authorizations which include the policy, as well as the doors and door groups targeted by the policy. Attributes: + id: The id of the policy. + name: The name given to the policy. + description: The description of the policy. + credential: The type of credential used to gain access. + 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: A schedule defining time periods where the policy is effective. None (null) means always. + authorizations: The list of authorizations that has this policy. + doors: The list of doors for which this policy applies to access from both inside and outside. + doorsInside: The list of doors for which this policy applies to access from the inside. + doorsOutside: The list of doors for which this policy applies to access from the outside. + doorGroups: 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. + Response 200 (application/json) [ { "id": "policy1", "name": "Ground floor - office hours", "description": "Optional description of the policy", "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" } ] } ] ### Create a New Policy [POST] Create new policies with this request. It takes an object of the same format as in the response to the GET request. Mandatory attributes: name, credential. 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]. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned if one or more of the specified authorizations, doors or door groups do not exist. In this case the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "name": "Ground floor - office hours", "description": "Optional description of the policy", "credential": "CARD", "schedule": { "id": "schedule1" }, "authorizations": [ { "id": "authorization1", }, { "id": "authorization2", } ], "doors": [ { "id": "door1", }, { "id": "door2", } ], "doorsInside": [], "doorsOutside": [], "doorGroups": [ { "id": "doorgroup1", }, { "id": "doorgroup2", } ] } + Response 200 (application/json) { "id": "policy1", "name": "Ground floor - office hours", "description": "Optional description of the policy", "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" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Ground floor - office hours", "info": "There already exists a policy with the name Ground floor - office hours." } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } ## Policy by ID [/v2/sys/{sys}/org/{org}/policies/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined policy that will be the target of the operation. ### Retrieve a Policy [GET] Retrieve the current definition of a policy with this request. Status code 400 and an explanatory object of type MISSING is returned if no policy can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "id": "policy1", "name": "Ground floor - office hours", "description": "Optional description of the policy", "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" } ] } + Response 400 (application/json) { "type": "MISSING", "issue": "policy5", "info": "There exists no policy with the id policy5." } ### Update a Policy [PUT] Update the definition of a policy with this request. It takes a policy object, same as POST, and replaces all values completely. Attributes may be omitted from the request in which case their values will not be affected. For the attributes doors, doorsInside, and doorsOutside this means that while values included in the request completely replace the corresponding existing value whereafter they are combined with the existing values that are not included, additively, as described for the POST request. For example where doors: [a], doorsInside: [b], doorsOutside: [c]... ...an update with just doorsInside: [a] results in doors: [a], doorsInside: [], doorsOutside: [c]. ...an update with just doors: [c] results in doors: [c], doorsInside: [b], doorsOutside: []. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use for a different policy. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned for either of four reasons: + No policy can be found for the target id. + One or more of the specified authorizations do not exist. + One or more of the specified doors do not exist. + One or more of the specified door groups do not exist. In this case, the attribute 'issue' will hold one of the missing id:s. + Request (application/json) { "name": "Ground floor - office hours", "description": "Optional description of the policy", "credential": "CARD", "schedule": { "id": "schedule1" }, "authorizations": [ { "id": "authorization1", }, { "id": "authorization2", } ], "doors": [ { "id": "door1", }, { "id": "door2", } ], "doorsInside": [], "doorsOutside": [], "doorGroups": [ { "id": "doorgroup1", }, { "id": "doorgroup2", } ] } + Response 200 (application/json) { "id": "policy1", "name": "Ground floor - office hours", "description": "Optional description of the policy", "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" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Ground floor - office hours", "info": "There already exists a policy with the name Ground floor - office hours." } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } ### Delete a Policy [DELETE] Use this request to irrevocably delete a policy. Status code 400 and an explanatory object of type MISSING is returned if no policy can be found for the target id. The attribute 'issue' will supply the id. + Response 200 + Response 400 (application/json) { "type": "MISSING", "issue": "policy5", "info": "There exists no policy with the id policy5." } ## Door Groups [/v2/sys/{sys}/org/{org}/doorgroups] + Parameters + sys - The id of the system. + org - The id of the organization. ### List All Door Groups [GET] This request will retrieve a list of all door groups. If there are no door groups, the list will be empty. A door group contains an attribute specifying the name, as well as the doors which are members of the group. The response also contains lists for all policies which target the door group. + Response 200 (application/json) [ { "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" } ] } ] ### Create a New Door Group [POST] Create new door groups with this request. It takes an object containing a name, and optional lists of policies and doors. Mandatory attributes: name Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned if one or more of the specified policies or doors do not exist. In this case the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "name": "Equipment rooms", "policies": [ { "id": "policy1", }, { "id": "policy2", } ], "doors": [ { "id": "door1", }, { "id": "door2", } ] } + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Equipment rooms", "info": "There already exists a door group with the name Equipment rooms." } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } ## Door Group by ID [/v2/sys/{sys}/org/{org}/doorgroups/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined door group that will be the target of the operation. ### Retrieve a Door Group [GET] Retrieve the current definition of a door group with this request. Status code 400 and an explanatory object of type MISSING is returned if no door group can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "MISSING", "issue": "doorgroup2", "info": "There exists no door group with the id doorgroup2." } ### Update a Door Group [PUT] Update the definition of a door group with this request. It takes a door group object, same as POST, and replaces all values completely. Attributes may be omitted from the request in which case their values will not be affected. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use for a different door group. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned for either of three reasons: + No door group can be found for the target id. + One or more of the specified policies do not exist. + One or more of the specified doors do not exist. In this case, the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "name": "Equipment rooms", "policies": [ { "id": "policy1", }, { "id": "policy2", } ], "doors": [ { "id": "door1", }, { "id": "door2", } ] } + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Equipment rooms", "info": "There already exists a door group with the name Equipment rooms." } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } ### Delete a Door Group [DELETE] Use this request to irrevocably delete a door group. Status code 400 and an explanatory object of type MISSING is returned if no door group can be found for the target id. The attribute 'issue' will supply the id. + Response 200 + Response 400 (application/json) { "type": "MISSING", "issue": "doorgroup2", "info": "There exists no door group with the id doorgroup2." } ## Events [/v2/sys/{sys}/org/{org}/events{?offset,before,after,limit,mintime,maxtime,token,user,method,reason,door,extended}] + Parameters + sys - The id of the system. + org - The id of the organization. + offset (number) - One of "offset", "before" or "after" can be used. This parameter controls the starting point of the events to be returned. + before (id) - One of "offset", "before" or "after" can be used. This parameter controls the starting point of the events to be returned. + after (id) - One of "offset", "before" or "after" can be used. This parameter controls the starting point of the events to be returned. + limit (number) - This parameter limits the maximum number of events to be retrieved. + mintime (millis) - Retrieve events that occur only after this timestamp, represented as the number of milliseconds since the epoch. + maxtime (millis) - Retrieve events that occur only before this timestamp, represented as the number of 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 (method) - Retrieve events that were caused by a method of a particular type only. + reason (reason 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. ### List Events [GET] This request will retrieve a list of events (log records). If there are no events, the list will be empty. Optional parameters can be specified in the request to filter the events retrieved. The response also contains objects with references to the related token, user, policy, door, command, trigger (if applicable, null if not). Note that only one of "offset", "before" or "after" can be used. Examples: + offset 0, limit 10 will return events 0 - 9 (the 10 most recent events) + offset 100, limit 10 will return the events in positions 100 - 109 + after id123, limit 5 will return the 5 events following the event with id123 in reverse chronological order + before id123, limit 4 will return the 4 events preceding the event with id123 in reverse chronological order In the response, the attribute logTime is expressed as a Unix timestamp (number of milliseconds since the epoch). The attribute method denotes the origin of the event and will be one of API, CARD, COMMAND, PIN, REMOTE, REX, SCHEDULE, TRIGGER, URL or UNDEFINED. The value API denotes the method called "Officer" elsewhere. The attribute reason provides the reason for the event. Possible values are: + 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 access requested 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. The attribute info will hold the card ID as read by the controller if reason is DENY_UNRECOGNIZED_TOKEN. Note that whether or not a particular event will occur is subject to controller and peripheral types and configurations. Status code 400 and an explanatory object of the type QUERY is returned if one of the following occurs: + More than one of the parameters "offset", "before", and "after" are included in the request + The value of 'offset' or 'limit' is negative. + If "before" or "after" is set to an unknown event id + If a filter parameter was set to an invalid value, such as when an unknown id is used for "user" + If an unrecognized parameter for "reason". + Response 200 (application/json) [ { "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 }, { "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 }, { "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 }, { "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" } } ] + Response 400 (application/json) { "type": "QUERY", "issue": null, "info": "At most one of the query parameters 'before', 'after', and 'offset', may be used at a time." } + Response 400 (application/json) { "type": "QUERY", "issue": "DENIED", "info": "DENIED is not recognized as a valid value for the 'reason' parameter." } ## Events by ID [/v2/sys/{sys}/org/{org}/events/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined event that will be the target of the operation. ### Retrieve an Event [GET] Retrieve the specified event with this request. Status code 400 and an explanatory object of type MISSING is returned if no event can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "id": "event4", "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" }, "command": null, "trigger: null } + Response 400 (application/json) { "type": "MISSING", "issue": "event4", "info": "There exists no event with the id event4." } ## Doors [/v2/sys/{sys}/org/{org}/doors] + Parameters + sys - The id of the system. + org - The id of the organization. ### List All Doors [GET] This request will retrieve a list of all doors. If there are no doors, the list will be empty. A door contains attributes specifying the name, description, door controller, policies, door groups and other configuration information. Attributes: + name: The name of the door. + description: Optional description of the door. + directional: Whether the door is directional (true) or not (false). + lockMode: May be UNLOCKED, LOCKED, DOUBLE_LOCKED, or UNKNOWN. + lockState: May be UNLOCKED, LOCKED, DOUBLE_LOCKED, UNKNOWN, or DETACHED. + lockStateOverride: May be UNLOCKED, LOCKED, DOUBLE_LOCKED, BLOCKED, or NONE. + doorMonitorState: May be CLOSED, OPEN, OPEN_TOO_LONG, FORCED_OPEN, or UNKNOWN. + controller: The door's controller if any. + hub: The hub through which this door is connected to the controller, if any. + policies: The list of policies that include this door. + visits: The list of visits that include this door. + doorGroups: The list of door groups that this controller is a member of. + accessSeconds: The number of seconds a door will be accessible for after access is granted. + openTooLongSeconds: The number of seconds that the door has to be held open to trigger an alarm. + preAlarmSeconds: The number of seconds that the door has to be held open to trigger a warning. + unlock: A schedule defining time periods when the door shall be unlocked. + unlockSecondary: A schedule defining time periods when the secondary lock (if any) shall be unlocked. For lockStateOverride, the value NONE is default and means that the door will be locked unless unlocked by a schedule. The value BLOCKED means that the door is locked and that all requests for access will be denied. The other values mean that the lock should always be in that state and that the attribute lockState should have that value. 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). The lockState value DETACHED applies only to wireless locks and means that the controller has lost contact with the lock. + Response 200 (application/json) [ { "id": "door1", "name": "Entrance door", "description": "Optional door description", "directional": true, "lockMode": "LOCKED", "lockState": "LOCKED", "lockStateOverride": "NONE", "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" } } ] ### Create a New Door [POST] Create new doors with this request. It takes an object of the same format as GET. The controller, lockMode, lockState, doorMonitorState, and hub attributes are read-only. LockStateOverride can only be set in a separate PUT request after the door is created. These attributes will be ignored if they are present in this request. Assignment of a controller or hub to a door is done via the controllers and hubs resource. Mandatory attributes: name. The attribute directional defaults to false. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use. In this case the attribute 'issue' will hold the conflicting value. Status code 400 and an explanatory object of the type MISSING is returned if one or more policies and/or door groups and/or schedules do not exist. In this case the attribute 'issue' will hold one of the the missing ids. + Request (application/json) { "name": "Entrance door", "description": "Optional door description", "directional": true, "policies": [ { "id": "policy1" }, { "id": "policy2" } ], "visits": [ { "id": "visit1", "name": "May marketing event" } ], "doorGroups": [ { "id": "doorgroup1" }, { "id": "doorgroup2" } ], "accessSeconds": 7, "openTooLongSeconds": 30, "preAlarmSeconds": 10, "unlock": { "id": "schedule2" }, "unlockSecondary": { "id": "schedule1" } } + Response 200 (application/json) { "id": "door1", "name": "Entrance door", "description": "Optional door description", "directional": true, "lockMode": "LOCKED", "lockState": "UNKNOWN", "lockStateOverride": "NONE", "doorMonitorState": "UNKNOWN", "controller": null, "hub": null, "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" } } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Entrance door", "info": "There already exists a door with the name Entrance door." } + Response 400 (application/json) { "type": "MISSING", "issue": "policy2", "info": "There exists no policy with the id policy2." } ## Door by ID [/v2/sys/{sys}/org/{org}/doors/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined door that will be the target of the operation. ### Retrieve a Door [GET] Retrieve the current definition of a door with this request. Status code 400 and an explanatory object of type MISSING is returned if no door can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "id": "door1", "name": "Entrance door", "description": "Optional door description", "directional": true, "lockMode": "LOCKED", "lockState": "LOCKED", "lockStateOverride": "NONE", "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" } } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } ### Update a Door [PUT] Update the definition of a door with this request. It takes a door object of the same format as POST, and replaces all values completely. All attributes except for the read-only lockMode, lockState, doorMonitorState, controller and hub can be changed. Attributes may be omitted from the request in which case their values will not be affected. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use for a different door. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned for either of these reasons: + No door can be found for the target id. + One or more of the specified policies, door groups, or schedules do not exist. In this case, the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "name": "Entrance door", "description": "Optional door description", "directional": false, "lockStateOverride": "UNLOCKED", "policies": [ { "id": "policy1" }, { "id": "policy2" } ], "visits": [ { "id": "visit1", "name": "May marketing event" } ], "doorGroups": [ { "id": "doorgroup1" }, { "id": "doorgroup2" } ], "accessSeconds": 7, "openTooLongSeconds": 30, "preAlarmSeconds": 10, "unlock": { "id": "schedule2" }, "unlockSecondary": { "id": "schedule1" } } + Response 200 (application/json) { "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" } } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Entrance door", "info": "There already exists a door with the name Entrance door." } + Response 400 (application/json) { "type": "MISSING", "issue": "doorgroup2", "info": "There exists no door group with the id doorgroup2." } + Response 400 (application/json) { "type": "CONNECTION", "issue": "anA1001", "info": "The controller is offline." } ### Delete a Door [DELETE] Use this request to irrevocably delete a door. Status code 400 and an explanatory object of type MISSING is returned if no door can be found for the target id. The attribute 'issue' will supply the id. + Response 200 + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with id door2." } ## Door Actions [/v2/sys/{sys}/org/{org}/doors/{id}/action] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined door that will be the target of the operation. ### Perform an action [PUT] Perform the grant access action on a door with this request. The attribute "action" may only have the value "GRANT_ACCESS". Status code 400 and an explanatory object of the type UNSUPPORTED is returned if the door is blocked. The value of the attribute 'issue' will be "BLOCKED". Status code 400 and an explanatory object of the type MISSING is returned if no door can be found for the target id. The attribute 'issue' will hold the target id. Status code 400 and an explanatory object of the type CONNECTION is returned if the action cannot be performed. The attribute 'issue' will hold the id of the controller. + Request (application/json) { "action": "GRANT_ACCESS" } + Response 200 (application/json) { "action": "GRANT_ACCESS", "door": { "id": "door1", "name": "Entrance door" } } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } + Response 400 (application/json) { "type": "CONNECTION", "issue": "anA1001", "info": "The controller is offline." } ## DEPRECATED Door States [/v1/sys/{sys}/org/{org}/doorstates/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined door that will be the target of the operation. ### Retrieve a Door's Door States [GET] This request is deprecated and will be removed in future API versions. Use doors/{id} and doors/{id}/action instead. Retrieve the current door state of a door with this request. Possible states are "ACCESSED", "UNLOCKED", "LOCKED", and "DOUBLE_LOCKED". Status code 400 and an explanatory object of type MISSING is returned if no door can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "id": "door1", "state": "DOUBLE_LOCKED" } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } ### Update a Door's Door States [PUT] This request is deprecated and will be removed in future API versions. Use doors/{id} and doors/{id}/action instead. Update the door state of a door with this request. It takes a door state object and replaces all values completely. Possible states are "ACCESSED", "UNLOCKED", "LOCKED", and "DOUBLE_LOCKED". Status code 400 and an explanatory object of the type VALUE is returned if the state entered is illegal. In this case, the attribute 'issue' will hold the illegal value. Status code 400 and an explanatory object of the type MISSING is returned if no door can be found for the target id. In this case, the attribute 'issue' will hold the target id. + Request (application/json) { "state": "ACCESSED" } + Response 200 (application/json) { "id": "door1", "state": "ACCESSED" } + Response 400 (application/json) { "type": "VALUE", "issue": "TRIPLE_LOCKED", "info": "There exists no state called 'TRIPLE_LOCKED'." } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } ## Controllers [/v2/sys/{sys}/org/{org}/controllers] + Parameters + sys - The id of the system. + org - The id of the organization. ### List All Controllers [GET] This request will retrieve a list of all controllers. If there are no controllers, the list will be empty. A controller contains attributes specifying the name, how and if the controller is reachable, and the configuration of all hardware connected to the controller. Attributes: + name: The name of the controller. + description: The description of the controller, if any. + type: The controller model. + "A1001": Denotes the Axis A1001. + "A1601": Denotes the Axis A1601. + "A9161": Denotes the Axis A9161. + timeZone: 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: How the controller is reached over the network. + 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: The current state of the connection to the controller as of the last attempt to connect. + 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: A message containing for details about the connection and any problems, if any. + address: 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: The MAC address retrieved from the controller, if connection to the controller is working. + internalIp: The internal ip of the controller. + fwVersion: The version of the firmware currently running the controller. + hub: The hub connected to this controller + id: The id of the hub. + name: The name of the hub. + doors: The array of all doors connected to the hub. + door: The id of the door. + name: The name of the door. + locks: The array of all locks connected to the controller. For each lock, the following attributes are defined: + port: Denotes socket/pin for connecting. This is used to determine the hardware terminals assigned to the 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: Whether the lock will be used as a primary or as a secondary lock + PRIMARY: If the lock is the primary lock. + SECONDARY: If the lock is the secondary lock. + mode: The mapping between port behavior and locked/unlocked. + ENGAGE_FAIL_SAFE: port or relay powered up when locked. + ENGAGE_FAIL_SECURE: port or relay powered down when locked. + door: The id and name of the door this lock is connected to. + monitors: The array of all door monitors connected to the controller. For each door monitor, the following attributes are defined: + port: Denotes socket/pin for connecting. + 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: The operation mode of this door monitor. + 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: The id and name of the door this door monitor is connected to. + readers: The array of readers connected to this controller. For each reader, the following attributes are defined: + port: Denotes socket/pin for connecting. + 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: The type of the reader. + 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: The id and name of the door this reader is connected to. + inside: Whether the reader is mounted inside (true) or outside (false). + rexButtons: The array of Request-To-Exit (REX) buttons connected to this controller. For each REX button, the following attributes are defined: + port: Denotes socket/pin for connecting. + 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. + action: Mode of operation of the REX button. + 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: The id and name of the door this reader is connected to. + ioPorts: The array of IO ports configured on this controller. For each IO port, the following attributes are defined: + port: Denotes pin for connecting, one of: + 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: 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. + Response 200 (application/json) [ { "id": "controller1", "description": null, "name": "Entrance controller", "type": "A1001", "timeZone": "CET", "connectionMode": "DIRECT", "connectionState": "CONNECTED", "connectionInfo": "Connection OK.", "address": "3.71.41.255:23000", "mac": "55:66:77:88:99:00", "internalIp": "127.0.0.1", "fwVersion": "1.65.0", "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": 2, "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" } } ], "ioPorts": [ { "port": 1, "type": "IN_NG" } ] } ] ### Create a New Controller [POST] Create new controllers with this request. It takes an object of the same format as in GET. The read-only attributes: internalIp, fwVersion, connectionState, connectionInfo and mac will be ignored if included. The firmware version (reflected in the fwVersion attribute) can be upgraded through the firmware resource. Mandatory attributes: name, type, timeZone, and connectionMode. The doors connected to the controller are determined by the set of doors assigned to locks. Therefore, only a door assigned to a lock can be assigned to any of the other peripheral types. For each lock defined, the port, usage, mode, and the id of the door are mandatory attributes. For readers the port, type, and id of the door are mandatory attributes, while inside is optional and defaults to false. For monitors and REX buttons the port, type, and id of the door are mandatory attributes. For each IO port defined (= configured), the port and type are mandatory attributes. A port number can only be used once per peripheral (lock, monitor,...) type. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use. In this case the attribute 'issue' will hold the conflicting value. Status code 400 and an explanatory object of the type MISSING is returned if no door can be found for the door id of a provided lock/monitor/reader/REX button. In this case, the attribute 'issue' will hold the missing id. Status code 400 and an explanatory object of the type VALUE is returned if the values provided for any of the attributes are invalid, such as when an invalid type is used for a reader. The attribute 'issue' will hold the invalid value in this case. + Request (application/json) { "name": "Entrance controller", "type": "A1001", "timeZone": "CET", "connectionMode": "DIRECT", "address": "3.71.41.255:23000", "hub": { "id": "hub1", }, "locks": [ { "port": 1, "usage": "PRIMARY", "mode": "ENGAGE_FAIL_SAFE", "door": { "id": "door1" } }, { "port": 2, "usage": "SECONDARY", "mode": "ENGAGE_FAIL_SAFE", "door": { "id": "door1" } } ], "monitors": [ { "port": 1, "type": "OPEN_CIRCUIT_OPEN_DOOR", "door": { "id": "door1" } } ], "readers": [ { "port": 3, "type": "RS485_HD_OSDP", "door": { "id": "door1" }, "inside": true } ], "rexButtons": [ { "port": 1, "type": "CLOSING_CIRCUIT_TRIGGERS", "door": { "id": "door1" } } ], "ioPorts": [ { "port": 1, "type": "IN_NG" } ] } + Response 200 (application/json) { "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": true } ], "rexButtons": [ { "port": 1, "type": "CLOSING_CIRCUIT_TRIGGERS", "door": { "id": "door1", "name": "Entrance door" } } ], "ioPorts": [ { "port": 1, "type": "IN_NG" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Entrance controller", "info": "There already exists a controller with the name Entrance controller." } + Response 400 (application/json) { "type": "VALUE", "issue": "WIEGAND_TRIPLE_LED", "info": "'WIEGAND_TRIPLE_LED' is not recognized as a valid type for a reader." } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } ## Controller by ID [/v2/sys/{sys}/org/{org}/controllers/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined controller that will be the target of the operation. ### Retrieve a Controller [GET] Retrieve the current definition of a controller and the states of any configured IO ports with this request. Status code 400 and an explanatory object of type MISSING is returned if no controller can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "id": "controller1", "name": "Entrance controller", "description": null, "type": "A1001", "timeZone": "CET", "connectionMode": "DIRECT", "connectionState": "CONNECTED", "connectionInfo": "Connection OK.", "address": "3.71.41.255:23000", "mac": "55:66:77:88:99:00", "internalIp": "127.0.0.1", "fwVersion": "1.65.0", "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": true } ], "rexButtons": [ { "port": 1, "type": "CLOSING_CIRCUIT_TRIGGERS", "door": { "id": "door1", "name": "Entrance door" } } ], "ioPorts": [ { "port": 1, "type": "IN_NG" } ] } + Response 400 (application/json) { "type": "MISSING", "issue": "controller2", "info": "There exists no controller with the id controller2." } ### Update a Controller [PUT] Update the definition of a controller with this request. It takes a controller object of the same format as GET, and replaces all values completely. The values that can be changed are the controller's name, description, type, time zone, hub, connection mode, address and associated locks, door monitors, readers and REX Buttons. Attributes may be omitted from the request in which case their values will not be affected. However, if the request changes the attribute 'type', it must also include the attribute 'locks'. As with POST, the doors connected to the controller are determined by the locks defined. Therefore, only doors connected to the locks can be connected to monitors, readers and rexButtons. As with POST, for each IO port defined (= configured), the port and type are mandatory attributes. If state is included it is ignored. Status code 400 and an explanatory object of the type UNSUPPORTED is returned if the request includes the attribute 'type' but not the attribute 'locks'. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use for a different door. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned for either of three reasons: + No controller can be found for the target id. + One or more of the specified doors do not exist. In this case, the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "name": "Entrance controller", "type": "A1001", "timeZone": "CET", "connectionMode": "DIRECT", "address": "3.71.41.255:23000", "hub": { "id": "hub1", }, "locks": [ { "port": 1, "usage": "PRIMARY", "mode": "ENGAGE_FAIL_SAFE", "door": { "id": "door1" } }, { "port": 2, "usage": "SECONDARY", "mode": "ENGAGE_FAIL_SAFE", "door": { "id": "door1" } } ], "monitors": [ { "port": 1, "type": "OPEN_CIRCUIT_OPEN_DOOR", "door": { "id": "door1" } } ], "readers": [ { "port": 3, "type": "RS485_HD_OSDP", "door": { "id": "door1" }, "inside": false } ], "rexButtons": [ { "port": 1, "type": "CLOSING_CIRCUIT_TRIGGERS", "door": { "id": "door1" } } ], "ioPort": [ { "port": 1, "type": "IN_NG" } ] } + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Entrance controller", "info": "There already exists a controller with the name Entrance controller." } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no controller with the id controller2." } ### Delete a Controller [DELETE] Use this request to irrevocably delete a controller. Status code 400 and an explanatory object of type MISSING is returned if no controller can be found for the target id. The attribute 'issue' will supply the id. + Response 200 + Response 400 (application/json) { "type": "MISSING", "issue": "controller2", "info": "There exists no door with id controller2." } ## Controller O3C Registration [/v2/sys/{sys}/org/{org}/controllers/{id}/o3c] Resource specifically 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 successfully deleted before creating a new one with the new details. + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined controller that will be the target of the operation. ### Create an O3C Registration [POST] Use this request to create a O3C registration for a controller. This request takes in an object containing the MAC address of the controller and the Owner Authentication Key (OAK), both of which are required. Status code 400 and an explanatory object of type O3C is returned if the details provided for the registration are incorrect or if a registration for this controller already exists. + Request (application/json) { "mac": "556677889900", "oak": "yuiwe87yuqqoiee" } + Response 200 + Response 400 (application/json) { "type": "O3C", "issue": "controller1", "info": "There already exists a registration for the controller with id controller1" } ### Retrieve an O3C Registration [GET] Use this request to retrieve the current registration for this controller, if any. Status code 400 and an explanatory object of type MISSING is returned if no registration can be found for the target controller or the target controller does not exist. The attribute 'issue' will supply the id of the controller. + Response 200 (application/json) { "mac": "556677889900", "oak": "yuiwe87yuqqoiee" } + Response 400 (application/json) { "type": "MISSING", "issue": "controller2", "info": "There exists no registration for the controller with id controller2." } ### Delete an O3C Registration [DELETE] Use this request to delete the current registration for this controller, if any. Status code 400 and an explanatory object of type MISSING is returned if the target controller does not exist. The attribute 'issue' will supply the id of the controller. Status code 400 and an explanatory object of type O3C is returned if the unregistration from O3C was unsuccessful for any reason. + Response 200 + Response 400 (application/json) { "type": "O3C", "issue": "controller1", "info": "Unregistering O3C for Entrance controller failed for reason: ..." } + Response 400 (application/json) { "type": "MISSING", "issue": "controller2", "info": "There exists no controller with id controller2." } ## Controller Actions [/v2/sys/{sys}/org/{org}/controllers/{id}/action] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined controller that will be the target of the operation. ### Perform an action [PUT] Perform the reset or the restart actions on a controller with this request. The attribute action may have the value RESET or RESTART. Status code 400 and an explanatory object of the type VALUE is returned if the action entered is illegal. In this case, the attribute 'issue' will hold the illegal value. Status code 400 and an explanatory object of the type MISSING is returned if no controller can be found for the target id. In this case, the attribute 'issue' will hold the target id. + Request (application/json) { "action": "RESET" } + Response 200 (application/json) { "action": "RESET", "controller": { "id": "controller1", "name": "Entrance controller" } } + Response 400 (application/json) { "type": "VALUE", "issue": "UPGRADE", "info": "There exists no action called 'UPGRADE'." } + Response 400 (application/json) { "type": "MISSING", "issue": "controller2", "info": "There exists no controller with the id controller2." } ## Controller Firmware Update [/v2/sys/{sys}/org/{org}/controllers/{id}/firmware] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined controller that will be the target of the operation. ### Retrieve an Initiated Firmware Update [GET] An initiated firmware update of a controller can be retrieved with this request. The attribute version will have a value that identifies firmware versions if an update has been initiated, or null if no update is on-going. Status code 400 and an explanatory object of the type MISSING is returned if no controller can be found for the target id. In this case, the attribute 'issue' will hold the target id. + Response 200 (application/json) { "version": "1.60.0.1", "controller": { "id": "controller1", "name": "Entrance controller" } } + Response 400 (application/json) { "type": "MISSING", "issue": "controller2", "info": "There exists no controller with the id controller2." } ### Initiate a Firmware Update [PUT] Initiate a firmware update of a controller with this request. The attribute version must have a value that identifies one of the available firmware versions by name. Status code 400 and an explanatory object of the type VALUE is returned if the version entered is unavailable. In this case, the attribute 'issue' will hold the unavailable value. Status code 400 and an explanatory object of the type MISSING is returned if no controller can be found for the target id. In this case, the attribute 'issue' will hold the target id. + Request (application/json) { "version": "1.60.0" } + Response 200 (application/json) { "version": "1.60.0", "controller": { "id": "controller1", "name": "Entrance controller" } } + Response 400 (application/json) { "type": "VALUE", "issue": "1.0.60", "info": "There exists no firmware version called '1.0.60'." } + Response 400 (application/json) { "type": "MISSING", "issue": "controller2", "info": "There exists no controller with the id controller2." } ## Available Firmware Version [/v2/sys/{sys}/firmwareversions] + Parameters + sys - The id of the system. ### Retrieve available firmware versions [GET] Retrieve the names of the firmware versions available per controller type with this request. Attributes: + controllerType: A controller type for which firmware is available. + versions: A list of names that will identify a firmware version for the controller type. This list may be empty. + Response 200 (application/json) [ { "controllerType": "A1001", "versions": ["1.57", "1.60.0", "1.60.0.1"] } { "controllerType": "A9999", "versions": [] } ] ## Hubs [/v2/sys/{sys}/org/{org}/hubs] + Parameters + sys - The id of the system. + org - The id of the organization. ### List All Hubs [GET] This request will retrieve a list of all hubs. If there are no hubs, the list will be empty. Attributes: + name: The name of the hub. + description: The description of the hub if any. + type: The hub model. + "APERIO": Denotes the ASSA Aperio. + "INTEGO": Denotes the SimonsVoss SmartIntego. + ipAddress: The ip address of the hub (does not matter when type is APERIO). + deviceAddress: The SmartIntego device address of the hub (does not matter when type is APERIO). + controller: The controller of the hub. + doors: The configuration of the wireless locks of the hub. + door: The door that has the wireless lock. + lockId: The Aperio lock id or the SmartIntego device address of the wireless lock. + monitorId: The Aperio monitor id or the SmartIntego phi string of the wireless lock. + Response 200 (application/json) [ { "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" } ] } ] ### Create a New Hub [POST] Create new hubs with this request. It takes an object containing a name, and an optional list of doors. The controller attribute is read-only, assignment of a controller to a hub is done via the controllers resource. Mandatory attributes: name and type. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned if one or more of the specified doors does not exist. In this case the attribute 'issue' will hold one of the missing ids. Status code 400 and an explanatory object of the type VALUE is returned if the values provided for any of the attributes are invalid, such as when an undefined value for type is used. The attribute 'issue' will hold the invalid value in this case. + Request (application/json) { "id": "hub1", "name": "Entrance hub", "description": "The hub connected to the entrance controller", "type": "INTEGO" "ipAddress":"192.168.1.43" "deviceAddress":"0x00000100" { "id": "controller1" }, "doors": [ { door: { "id": "door2" }, lockId: "0x00000200", monitorId: "00E8E3F" }, { door: { "id": "door3" }, lockId: "0x00000300", monitorId: "00F24KM" } ] } + Response 200 (application/json) { "id": "hub1", "name": "Entrance hub", "description": "The hub connected to the entrance controller", "type": "INTEGO" "ipAddress":"192.168.1.43" "deviceAddress":"0x00000100" { "id": "controller1", "name": "Entrance controller" }, "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" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Entrance hub", "info": "There already exists a hub with the name Entrance hub." } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } + Response 400 (application/json) { "type": "VALUE", "issue": "A1001", "info": "'A1001' is not recognized as a valid type for a hub." } ## Hub by ID [/v2/sys/{sys}/org/{org}/hubs/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined hub that will be the target of the operation. ### Retrieve a Hub [GET] Retrieve the current definition of a hub with this request. Status code 400 and an explanatory object of type MISSING is returned if no hub can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "id": "hub1", "name": "Entrance hub", "description": "The hub connected to the entrance controller", "type": "INTEGO" "ipAddress":"192.168.1.43" "deviceAddress":"0x00000100" { "id": "controller1", "name": "Entrance controller" }, "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" } ] } + Response 400 (application/json) { "type": "MISSING", "issue": "hub2", "info": "There exists no hub with the id hub2." } ### Update a Hub [PUT] Update the definition of a hub with this request. It takes a hub object, same as POST, and replaces all values completely. Attributes may be omitted from the request in which case their values will not be affected. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use for a different hub. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned for either of two reasons: + No hub can be found for the target id. + One or more of the specified doors do not exist. In this case, the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "doors": [ { door: { "id": "door2" }, lockId: "lock2", monitorId: "monitor2" } ] } + Response 200 (application/json) { "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: "lock2", monitorId: "monitor2" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Entrance hub", "info": "There already exists a hub with the name Entrance hub. } + Response 400 (application/json) { "type": "MISSING", "issue": "door4", "info": "There exists no door with the id door4." } ### Delete a Hub [DELETE] Use this request to irrevocably delete a hub. Status code 400 and an explanatory object of type MISSING is returned if no hub can be found for the target id. The attribute 'issue' will supply the id. + Response 200 + Response 400 (application/json) { "type": "MISSING", "issue": "hub2", "info": "There exists no hub with the id hub2." } ## Pin Chart [/v2/sys/{sys}/org/{org}/controllers/{id}/pinchart] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined controller that will be the target of the operation. ### Retrieve a Pin Chart [GET] Retrieve the current pin chart for a controller with this request. Status code 400 and an explanatory object of type MISSING is returned if no controller can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) [ { "device": "Entrance Lock 1", "connections": [ { "socket": "LOCK", "terminal": "-", "wire": "GND" }, { "socket": "LOCK", "terminal": "H1", "wire": "OUT" } ] }, { "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" } ] } ] + Response 400 (application/json) { "type": "MISSING", "issue": "controller2", "info": "There exists no controller with the id controller2." } ## Schedules [/v2/sys/{sys}/org/{org}/schedules] + Parameters + sys - The id of the system. + org - The id of the organization. ### List All Schedules [GET] This request will retrieve a list of all defined schedules. If there are no schedules the list will be empty. + Response 200 (application/json) [ { "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" } ] } ] ### Create a New Schedule [POST] Create new schedules with this request. It takes an object containing a name, a description, and a set of time periods. The policies and doors attributes are read only. Mandatory attributes: name. 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. Example: {"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. Example: {"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. Status code 400 and an explanatory object of the type VALUE is returned if a date/time does not match the above format and the attribute 'issue' will hold the problematic value. This will also happen if a weekday symbol is unrecognized. Status code 400 and an explanatory object of the type VALUE is returned if a resulting date or time interval is specified to end before it begins. In this case the attribute 'issue' will hold the start of the problematic interval. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use. In this case the attribute 'issue' will hold the conflicting name. + Request (application/json) { "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" } ] } } + Response 200 (application/json) { "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": [], "doors": [] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Office hours", "info": "There already exists a schedule with the name Office hours." } + Response 400 (application/json) { "type": "VALUE", "issue": "2117-11-23" "info": "There is an interval that starts 2117-11-23 after it ends 2017-11-19." } ## Schedule by ID [/v2/sys/{sys}/org/{org}/schedules/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined schedule that will be the target of the operation. ### Retrieve a Schedule [GET] Retrieve the current definition of a schedule with this request. The response will include the name, the description, the included and the exclude time periods, and the doors and the policies that reference the schedule. Status code 400 and an explanatory object of type MISSING is returned if no schedule can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "MISSING", "issue": "schedule1", "info": "There exists no schedule with the id schedule1." } ### Update a Schedule [PUT] Update the definition of a schedule with this request. It takes a schedule object, same as POST, and replaces all values completely. Attributes may be omitted from the request in which case their values will not be affected. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use for a different schedule. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned if no schedule can be found for the target id and the attribute 'issue' will hold the id. + Request (application/json) { "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" } ] } } + Response 200 (application/json) { "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": [], "doors": [] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Office hours", "info": "There already exists a schedule with the name Office hours." } + Response 400 (application/json) { "type": "VALUE", "issue": "2117-11-23" "info": "There is an interval that starts 2117-11-23 after it ends 2017-11-19." } + Response 400 (application/json) { "type": "MISSING", "issue": "schedule4", "info": "There exists no schedule with the id schedule4." } ### Delete a Schedule [DELETE] Use this request to irrevocably delete a schedule. Status code 400 and an explanatory object of the type MISSING is returned if no schedule can be found for the target id. The attribute 'issue' will supply the id. + Response 200 + Response 400 (application/json) { "type": "MISSING", "issue": "schedule4", "info": "There exists no schedule with the id schedule4." } ## Visits [/v2/sys/{sys}/org/{org}/visits] + Parameters + sys - The id of the system. + org - The id of the organization. ### List All Visits [GET] This request will retrieve a list of all visits. If there are no visits, the list will be empty. A visit contains an attribute specifying which credential is used to gain access, and a schedule. The response also contains lists for all authorizations which include the visit, as well as the doors and door groups targeted by the visit. Attributes: + id: The id of the visit. + name: The internal name given to the visit. + description: The external name given to the visit. + credentials: All list of the types of credential that can be used to gain access. May include one or both of + PIN: A PIN is required to gain access. + URL: Visiting a URL is required to gain access. + validFrom: The first second access shall be allowed on the format yyyy-MM-ddTHH:mm:ss, e.g. 2017-11-23T00:00:00, in the timezone of the controller. + validTo: The last second to be included in the interval denoted as above. + pin: The PIN that allows access. + url: The URL that allows access. + schedule: A schedule defining time periods where the visit is effective. + doors: The list of doors this visit applies to. + Response 200 (application/json) [ { "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" } ] } ] ### Create a New Visit [POST] Create new visits with this request. It takes an object containing a name, a list of credentials, a PIN, a validity period, a schedule, and a list of doors targeted by the visit. Mandatory attributes: name and credentials. The PIN is optional and if not specified, a random value will be provided. Attributes validFrom and validTo both default to null, which represents infinite negative and infinite positive time respectively. Attribute schedule defaults to null meaning that the visit is active at all times. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned if one or more of the specified authorizations, doors or door groups do not exist. In this case the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "name": "May marketing event", "description": "Open house", "credentials": ["PIN","URL"], "validFrom": "2017-06-25T18:30:00", "validTo": "2017-06-25T20:00:00", "schedule": { "id": "schedule1" }, "doors": [ { "id": "door1", } ] } + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "May marketing event", "info": "There already exists a visit with the name May marketing event." } + Response 400 (application/json) { "type": "MISSING", "issue": "door1", "info": "There exists no door with the id door1." } ## Visit by ID [/v2/sys/{sys}/org/{org}/visits/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined visit that will be the target of the operation. ### Retrieve a Visit [GET] Retrieve the current definition of a visit with this request. Status code 400 and an explanatory object of type MISSING is returned if no visit can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "MISSING", "issue": "visit5", "info": "There exists no visit with the id visit5." } ### Update a Visit [PUT] Update the definition of a visit with this request. It takes a visit object, same as POST, and replaces all values completely. Attributes may be omitted from the request in which case their values will not be affected. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use for a different visit. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned for either of four reasons: + No visit can be found for the target id. + One or more of the specified authorizations do not exist. + One or more of the specified doors do not exist. + One or more of the specified door groups do not exist. In this case, the attribute 'issue' will hold one of the missing id:s. + Request (application/json) { "name": "May marketing event", "description": "Open house", "credentials": ["PIN","URL"], "validFrom": "2017-06-25T18:30:00", "validTo": "2017-06-25T20:00:00", "schedule": { "id": "schedule1" }, "doors": [ { "id": "door1", } ] } + Response 200 (application/json) { "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" } ] } + Response 400 (application/json) { "type": "CONFLICT", "issue": "May marketing event", "info": "There already exists a visit with the name May marketing event." } + Response 400 (application/json) { "type": "MISSING", "issue": "door1", "info": "There exists no door with the id door1." } ### Delete a Visit [DELETE] Use this request to irrevocably delete a visit. Status code 400 and an explanatory object of type MISSING is returned if no visit can be found for the target id. The attribute 'issue' will supply the id. + Response 200 + Response 400 (application/json) { "type": "MISSING", "issue": "visit5", "info": "There exists no visit with the id visit5." } ## Event Notifications [/v2/sys/{sys}/org/{org}/notifications] + Parameters + sys - The id of the system. + org - The id of the organization. ### List All Event Notifications [GET] This request will retrieve a list of all event notifications. If there are none, the list will be empty. Attributes: + name: The name of the event notification. + description: The description of the event notification. + minMillisBetween: Least time between notification deliveries. Deliveries are skipped to comply. + reasons: Only consider events with one of these reason attribute values. Possible values are documented here: https://v2accessmanageradmin.docs.apiary.io/#reference/requests/events. + recipientsSms: List of international format phone numbers to deliver to. + recipientsEmail: List of email addresses to deliver to. + recipientsHttp: List of HTTP (or HTTPS) listeners to deliver to. + onlyDuring: Only consider events that occur when this schedule is active. + unlessDuring: Only consider events that do not occur when this schedule is active. + onlyControllers: Only consider events with one of these controller attribute values. + onlyTokens: Only consider events with one of these token attribute values. + onlyDoors: Only consider events with a door attribute value that is listed or contained in at least one of the door groups. + onlyMethods: Only consider events with one of these method attribute values. Possible values are documented here: https://v2accessmanageradmin.docs.apiary.io/#reference/requests/events. + onlyUsers: Only consider events with a user attribute value that is listed or contained in at least one of the authorizations. + Response 200 (application/json) [ { "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" } ], "authorizations": [ { "id": "authorization1", "name": "Catering" } ] } } ] ### Create an Event Notification [POST] Create new event notifications with this request. Mandatory attributes: name, minMillisBetween, reasons. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned if one or more of the specified entities do not exist. In this case the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "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" }, "unlessDuring": { "id": "schedule2" }, "onlyControllers": [ { "id": "controller1" } ], "onlyTokens": [ { "id": "token1" } ], "onlyDoors": { "doors": [ { "id": "door1" } ], "doorsGroups": [ { "id": "doorgroup1" } ] }, "onlyMethods": [ "CARD" ], "onlyUsers": { "users": [ { "id": "user1" } ], "authorizations": [ { "id": "authorization1" } ] } } + Response 200 (application/json) { "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" } ], "authorizations": [ { "id": "authorization1", "name": "Catering" } ] } } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Watch for Alice", "info": "There already exists an event notification with the name Watch for Alice." } + Response 400 (application/json) { "type": "MISSING", "issue": "door1", "info": "There exists no door with the id door1." } ## Event Notification by ID [/v2/sys/{sys}/org/{org}/notifications/{id}] + Parameters + sys - The id of the system. + org - The id of the organization. + id - The id of a previously defined door group that will be the target of the operation. ### Retrieve an Event Notification [GET] Retrieve the current definition of an event notification with this request. Status code 400 and an explanatory object of type MISSING is returned if no event notification can be found for the target id. The attribute 'issue' will supply the id. + Response 200 (application/json) { "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" } ], "authorizations": [ { "id": "authorization1", "name": "Catering" } ] } } + Response 400 (application/json) { "type": "MISSING", "issue": "eventnotification2", "info": "There exists no event notification with the id eventnotification2." } ### Update an Event Notification [PUT] Update the definition of an event notification with this request. Attributes may be omitted from the request in which case their values will not be affected. Supplied attributes will be replaced completely. Status code 400 and an explanatory object of the type CONFLICT is returned if the name is already in use for a different event notification. In this case the attribute 'issue' will hold the conflicting name. Status code 400 and an explanatory object of the type MISSING is returned for either of two reasons: + No event notification can be found for the target id. + One or more of the specified entities do not exist. In this case, the attribute 'issue' will hold one of the missing ids. + Request (application/json) { "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" }, "unlessDuring": { "id": "schedule2" }, "onlyControllers": [ { "id": "controller1" } ], "onlyTokens": [ { "id": "token1" } ], "onlyDoors": { "doors": [ { "id": "door1" } ], "doorsGroups": [ { "id": "doorgroup1" } ] }, "onlyMethods": [ "CARD" ], "onlyUsers": { "users": [ { "id": "user1" } ], "authorizations": [ { "id": "authorization1" } ] } } + Response 200 (application/json) { "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" } ], "authorizations": [ { "id": "authorization1", "name": "Catering" } ] } } + Response 400 (application/json) { "type": "CONFLICT", "issue": "Equipment rooms", "info": "There already exists a door group with the name Equipment rooms." } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } ### Delete an Event Notification [DELETE] Use this request to irrevocably delete an event notification. Status code 400 and an explanatory object of type MISSING is returned if no event notification can be found for the target id. The attribute 'issue' will supply the id. + Response 200 + Response 400 (application/json) { "type": "MISSING", "issue": "eventnotification2", "info": "There exists no event notification with the id eventnotification2." } ## Request Access by Token CID [/v2/sys/{sys}/org/{org}/access/doors/{door}/tokens] + Parameters + sys - The id of the system. + org - The id of the organization. + door - The id of the door for which access is requested. ### Perform request access [POST] Specify a token by CID to request access to a door with this request. Attributes: + authorization: One (of possibly several) matching authorizations; or null if none. + cid: The token CID. + credentials: A list of the considered credentials; policies must match at least one. + door: The door for which access is requested. + granted: Set to true if access was granted, false otherwise. + pin: The PIN used if any; otherwise null. + policy: One (of possibly several) matching policies; or null if none. + reason: The reason for a denied request. See events for a list of possible values. + token: The token that matches the CID, or null if none. + user: The user of the token that matches the CID, or null if none. In the request the attribute "cid" is mandatory and the attribute "pin" is optional. The remaining attributes are only relevant to the response. 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. Status code 400 and an explanatory object of the type MISSING is returned if no door can be found for the door id. The attribute 'issue' will then hold the door id. Status code 400 and an explanatory object of the type CONNECTION is returned if the action cannot be performed. The attribute 'issue' will hold the id of the controller. + Request (application/json) { "cid": "456678768", "pin": "1234" } + Response 200 (application/json) { "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" } } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } + Response 400 (application/json) { "type": "CONNECTION", "issue": "anA1001", "info": "The controller is offline." } ## Request Access by Token ID [/v2/sys/{sys}/org/{org}/access/doors/{door}/tokens/{token}] + Parameters + sys - The id of the system. + org - The id of the organization. + door - The id of the door for which access is requested. + token - The id of the token to be used. ### Perform request access [POST] Specify a card type (CID or CNR) token by ID to request access to a door with this request. Attributes: + authorization: One (of possibly several) matching authorizations; or null if none. + cid: The token CID. + credentials: A list of the considered credentials; policies must match at least one. + door: The door for which access is requested. + granted: Set to true if access was granted, false otherwise. + pin: The PIN used if any; otherwise null. + policy: One (of possibly several) matching policies, or null if none. + reason: The reason for a denied request. See events for a list of possible values. + token: The token. + user: The user of the token, or null if none. In the request the attribute "pin" is optional and the remaining attributes are only relevant to the response. 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. Status code 400 and an explanatory object of the type UNSUPPORTED is returned if the token is not of type CID or CNR. The attribute 'issue' will then hold the token id. Status code 400 and an explanatory object of the type MISSING is returned if no door can be found for the door id. The attribute 'issue' will then hold the door id. Status code 400 and an explanatory object of the type CONNECTION is returned if the action cannot be performed. The attribute 'issue' will hold the id of the controller. + Request (application/json) { "pin": "1234" } + Response 200 (application/json) { "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" } } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } + Response 400 (application/json) { "type": "CONNECTION", "issue": "anA1001", "info": "The controller is offline." } ## Request Access by User PIN [/v2/sys/{sys}/org/{org}/access/doors/{door}/users] + Parameters + sys - The id of the system. + org - The id of the organization. + door - The id of the door for which access is requested. ### Perform request access [POST] Specify a user by pin to request access to a door with this request. If the PIN matches several users access will be granted unless denied for all. Attributes: + authorization: One (of possibly several) matching authorizations; or null if none. + credentials: A list of the considered credentials; policies must match at least one. + door: The door for which access is requested. + granted: Set to true if access was granted, false otherwise. + pin: The PIN used. + policy: One (of possibly several) matching policies; or null if none. + reason: The reason for a denied request. See events for a list of possible values. + user: A user (of possibly several) that matches the PIN; or null if none. In the request the attribute "pin" is optional and the remaining attributes are only relevant to the response. 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. Status code 400 and an explanatory object of the type MISSING is returned if no door can be found for the door id. The attribute 'issue' will then hold the door id. Status code 400 and an explanatory object of the type CONNECTION is returned if the action cannot be performed. The attribute 'issue' will hold the id of the controller. + Request (application/json) { "pin": "1234" } + Response 200 (application/json) { "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" } } + Response 400 (application/json) { "type": "MISSING", "issue": "door2", "info": "There exists no door with the id door2." } + Response 400 (application/json) { "type": "CONNECTION", "issue": "anA1001", "info": "The controller is offline." } ## Request Access by User ID [/v2/sys/{sys}/org/{org}/access/doors/{door}/users/{user}] + Parameters + sys - The id of the system. + org - The id of the organization. + door - The id of the door for which access is requested. + user - The id of the user for whom access is requested. ### Perform request access [POST] Specify a user by id to request access to a door with this request. Only policies that allow credentials API_1 or API_2 can match this request. Attributes: + authorization: One (of possibly several) matching authorizations; or null if none. + credentials: A list of the considered credentials; policies must match at least one. + door: The door for which access is requested. + granted: Set to true if access was granted, false otherwise. + policy: One (of possibly several) matching policies; or null if none. + reason: The reason for a denied request. See events for a list of possible values. + user: The user for whom access is requested. 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. 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. Status code 400 and an explanatory object of the type MISSING is returned if the door or the user cannot be found for the given ids. The attribute 'issue' will then hold the unidentified id. Status code 400 and an explanatory object of the type CONNECTION is returned if the action cannot be performed. The attribute 'issue' will hold the id of the controller. + Request (application/json) { "credentials": ["API_1"] } + Response 200 (application/json) { "authorization": { "id": "authorization1", "name": "IT Technician" }, "credentials": ["API_1"], "door": { "id": "door1", "name": "Entrance door" }, granted: true, "policy": { "id": "policy1", "name": "Ground floor - office hours" }, "reason": "ACCESS", "user": { "id": "user1", "name": "Alice Smith" } } + Response 400 (application/json) { "type": "MISSING", "issue": "user2", "info": "There exists no user with the id user2." } + Response 400 (application/json) { "type": "CONNECTION", "issue": "anA1001", "info": "The controller is offline." } # Group Other Things ## 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. ### Unauthorized Access Error [PUT] Status code 400 and an explanatory object of the type 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. + Response 400 (application/json) { "type": "UNAUTHORIZED", "issue": "BadCop" "info": "Sign in failed for 'BadCop'." } ## Common Error Responses [/...] In addition to the error responses CONFLICT and MISSING described and exemplified above, the responses listed in this section are also possible, in many ways independent of the request. ### Inapplicable Method Error [PATCH] Status code 400 and an explanatory object of the type METHOD is returned if the method of the request (GET/PUT/...) is not applicable to the resource given by the path of the request. + Response 400 (application/json) { "type": "METHOD", "issue": null "info": "The method (GET/PUT/POST/DELETE) is not defined for this resource." } ### Unknown Path Error [POST] Status code 400 and an explanatory object of the type PATH is returned if the path of the request is not recognized. + Response 400 (application/json) { "type": "PATH", "issue": null "info": "This resource is not defined." } ### Error in Query [GET] Status code 400 and an explanatory object of the type QUERY is returned if the request includes a query that cannot be interpreted or makes no sense. + Response 400 (application/json) { "type": "QUERY", "issue": null "info": "The query parameter 'limit' must be numeric." } ### API Version Error [DELETE] Status code 400 and an explanatory object of the type VERSION is returned if the body of the response would contain objects that are not compatible with the current version of the API. The attribute issue will hold the id of one of the incompatible object. + Response 400 (application/json) { "type": "VERSION", "issue": "49" "info": "The controller with id 49 controls more than two doors." } ## Common Error Responses to POST and PUT Requests [/....] The responses listed in this section are also possible for POST and PUT resquests. ### Body Unknown Attribute Error [POST] Status code 400 and an explanatory object of the type SYNTAX is returned if the body of a PUT or Post is not proper JSON. The attribute issue will hold the line and the column where the syntax error was discovered as a JSON list. + Response 400 (application/json) { "type": "ATTRIBUTE", "issue": "type" "info": "The attribute type is unknown. Expecting one of [port, usage, mode, door]" } ### Body Syntax Error [PUT] Status code 400 and an explanatory object of the type SYNTAX is returned if the body of a PUT or Post is not proper JSON. The attribute issue will hold the line and the column where the syntax error was discovered as a JSON list. + Response 400 (application/json) { "type": "SYNTAX", "issue": "[2, 30]" "info": "The request body is not proper JSON: missing type at line 2, column 30." } ### Body Value Error [OPTIONS] Status code 400 and an explanatory object of the type VALUE is returned if the body of a PUT or Post specifies an illegal value. The attribute issue will hold the value. + Response 400 (application/json) { "type": "VALUE", "issue": "ALL" "info": "There is no authorization type called 'ALL'." }