v2 Telcred Access Manager Admin API

This API allows you to perform access management in Telcred Access Manager.

Before you start, you need to have at least one account ID, one system ID, and sign-in credentials (username and password) with access management capacity.

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.

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.

You are assumed to be familiar with Telcred Access Manager through its user interface and documentation.

The resources Authorizations, Tokens, and Policies, correspond to Roles, Cards, and Privileges, respectively.

All requests are authenticated using HTTP Basic Auth. Any officer with access management capacity can be used. You can match this to users of the client application or have a dedicated API user as you see fit.

The body of a request or a response is either a single object or an array of objects. In actions that include both a request and a response object, the type of the object will be the same, e.g. creating a user takes a user as input and returns a user as output. Yet, while the response will include all attributes of the object, it is usually not necessary to include all the attributes in the request.

The content type for both request body and response body is application/json.

For a request that has been processed without error, the response status code is 200.

If processing the request fails, the response status code is always 400. See the section Error Responses.

This documentation is structured by resource (controllers, users, ...). Each section starts out by listing the actions (list, create, ...) that can be performed on the resource, specifying the HTTP method, the URL, the request body, and the response body, for each.

For example, in the Users section

declares that users are listed through a GET request that will return an array of user object.

These parameters are used in URL specifications (see the example above):

The account id and the system id are displayed on the info screens in Telcred System Manager.

The system id can also be found through the Telcred Access Manager Owner API.

The ids for the target objects are provided in the API responses below.

The specification of the attributes lists them as mandatory, optional, or ignored:

• mandatory:

  • In create requests, a value must be provided.
  • In update requests, the attribute is optional.

• optional: A value may be provided when relevant.

  • In create requests, when omitted, unless otherwise noted, a single value will default to null and an array value will default to an empty array.
  • In update requests, when omitted, the existing value will remain unchanged.

• ignored: only relevant in responses, a value provided in a request will be disregarded.

The specification of the attributes also declare their types. Types may be the native JSON types number, boolean, string, array, or another object. Such embedded objects are either described in the same section or are of the type Object Reference.

The Object Reference object is frequently used in place of any object with an id, representing that object. It only has one mandatory attribute, the id. The name and reference properties of the referenced object are included as a second and third attribute. These attributes are ignored rather than mandatory, so they do not have to be supplied in requests, but will be supplied in responses, as a convenience.

This is the specification of the Object Reference object:

{
    "id": "196458",
    "name": "Alice Smith",
    "reference": "YYKHJV"
}

This is the specification of the attributes:

id (string) mandatory

The id of the object.

name (string) ignored

The name of the object.

reference (string) ignored

The reference property of the object.

The following requests are performed using officer "officer", with password "password", for authorization.

Create a user named Alice, in account 1, system 4043:

curl -X POST -H "Content-Type: application/json" \
-u officer:password \
https://access.telcred.com/v2/sys/1/org/4043/users \
-d '{"name": "Alice Smith"}'

Response body:

{
  "id": "318069",
  "authorizations": [ ],
  "blocked": false,
  "name": "Alice Smith",
  "reference": "YYKHJV",
  "pin": null,
  "tokens": [ ]
}

Note 1: that although the object type (user) of the response is also required for the request, only the name attribute is mandatory and has to be provided.

Note 2: that the response includes the full set of attributes. This is always the case.

Create a token for Alice using the id from the response above:

curl -X POST -H "Content-Type: application/json" \
-u officer:password \
https://access.telcred.com/v2/sys/1/org/4043/tokens \
-d '{"name": "Alice Badge", "type": "CID", "cid": "AABBCCDDEE", "user": {"id": "318069"}}'

Response body:

{
  "id": "80954",
  "blocked": false,
  "cid": "AABBCCDDEE",
  "description": null,
  "name": "Alice Badge",
  "type": "CID",
  "user": {
    "id": "318069",
    "name": "Alice Smith",
    "reference": "YYKHJV"
  },
  "userFrom": null,
  "userTo": null
}

Note 1: the use of the Object Reference to denote the previously created user.

Note 2: that in the Object Reference, only the id attribute is mandatory and has to be provided in the request.

Update Alice with a PIN code:

curl -X PUT -H "Content-Type: application/json" \
-u officer:password \
https://access.telcred.com/v2/sys/1/org/4043/users/318069 \
-d '{"pin": "1106"}'

Response body:

{
  "id": "318069",
  "authorizations": [ ],
  "blocked": false,
  "name": "Alice Smith",
  "pin": "1106",
  "tokens": [
    {
      "id": "80954",
      "name": "Alice Badge",
      "reference": "YYKHJV",
      "userFrom": null,
      "userTo": null
    }
  ]
}

Note 1: that only the attributes (pin) to be changed was provided in the request.

Note 2: in a few cases, a richer object than the regular Reference Object is used.

Retrieve token 80954 referenced in the response above:

curl -X GET \
-u officer:password \
https://access.telcred.com/v2/sys/1/org/4043/tokens/80954

Response body:

{
  "id": "80954",
  "blocked": false,
  "cid": "AABBCCDDEE",
  "description": null,
  "name": "Alice Badge",
  "type": "CID",
  "user": {
    "id": "318069",
    "name": "Alice Smith",
    "reference": "YYKHJV"
  },
  "userFrom": null,
  "userTo": null
}

Delete the token with id 80954:

curl -X DELETE \
-u officer:password \
https://access.telcred.com/v2/sys/1/org/4043/tokens/80954

Note: the response has no body in this case.

List all tokens:

curl -X GET \
-u officer:password \
https://access.telcred.com/v2/sys/1/org/4043/tokens/

Response body:

[ ]

Note: If there are none, the response body will be an empty list.

List all users:

curl -X GET \
-u officer:password \
https://access.telcred.com/v2/sys/1/org/4043/users/

Response body:

[
  {
    "id": "318069",
    "authorizations": [ ],
    "blocked": false,
    "name": "Alice Smith",
    "reference": "YYKHJV",
    "pin": "1106",
    "tokens": [ ]
  }
]

"Authorizations" are known as "Roles" in the Access Manager UI.

{
  "id": "authorization1",
  "name": "IT technician",
  "reference": "YYKHJV",
  "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"
    }
  ]
}

id (string) ignored

The id of the authorization.

name (string) mandatory

The name of the authorization.

reference (string) optional

The reference property of the authorization.

type (string) optional

Legacy attribute which is no longer in use. One of ROLE or ASSIGNMENT. Defaults to ROLE.

validFrom (number) mandatory

Validity start in milliseconds from 1970-01-01T00:00:00 in the time zone of the controller.

validTo (number) mandatory

Validity end in milliseconds from 1970-01-01T00:00:00 in the time zone of the controller.

policies (array[object reference]) optional

The policies this authorization provides.

users (array[object reference]) optional

The users with this authorization.

{
  "id": "controller1",
  "name": "Entrance controller",
  "reference": "YYKHJV",
  "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"
      }
    ]
  },
  "hubs": [
    {
      "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"
    }
  ]
}

id (string) ignored

The id of the controller.

name (string) mandatory

The name of the controller.

reference (string) optional

The reference property of the controller.

type (string) mandatory

The controller model. One of

• "A1001": Denotes the Axis A1001.

• "A1210": Denotes the Axis A1210.

• "A1601": Denotes the Axis A1601.

• "A1610": Denotes the Axis A1610.

• "A9161": Denotes the Axis A9161.

• "A9188": Denotes the Axis A9188.

timeZone (string) mandatory

The time zone of the controller, represented as a string. This string must be the canonical ID of the desired time zone as defined by the tz database. A full list of supported time zones with canonical IDs can be found here: wikipedia.org.

connectionMode (string) mandatory

How the controller is reached over the network. One of

• DIRECT: if the controller is connected directly via its IP address.

• O3C: if the controller is connected via the One-Click connection service. Do note that configuration to the One-Click connection service is done separately via its own API.

• SHORTCUT: if the controller is connected via a shortcut. See Shortcut Generators in the Owners API.

connectionState (string) ignored

The current state of the connection to the controller as of the last attempt to connect. One of

• CONNECTED: if the latest attempt to connect to the controller succeeded.

• DISCONNECTED: if the latest attempt to connect to the controller failed.

• UNCONFIGURED: if the connection details for this controller have not been provided.

• UNDEFINED: if connection to the controller has not been attempted yet.

connectionInfo (string) ignored

Details regarding the connection state intended for human consumption.

address (string) optional

How to reach the controller if connectionMode is not O3C.

• If connectionMode is DIRECT, the format is 'ip:port', e.g. 192.168.1.1:43

• If connectionMode is SHORTCUT, the format is 'shortcut name:external controller id', e.g. demo:43.

mac (string) ignored

The MAC address retrieved from the controller (if connection to the controller has worked).

internalIp (string) ignored

The local IP address retrieved from the controller (if connection to the controller has worked).

fwVersion (string) ignored

The version of the firmware currently running the controller.

hub (hub reference) optional deprecated

The hub connected to this controller, if zero or one. While this attribute is included for backward compatibility, its use is discouraged in favor of the attribute "hubs" below. Values are interpreted like this:

• In a response, the attribute shows the connected hub as long as the controller has only one. If there is more than one, the value will be null.

• In a post/put request, including a hub reference as the value will set that hub as the controller's only hub.

• In a post/put request, including null as the value will remove all hubs from the controller if the attribute hubs (see below) is not included in the request.

hubs (hub reference) optional

The hubs connected to this controller. Use this attribute rather than the deprecated attribute hub.

• In a response, the attribute always shows all the controller's hubs.

• In a post/put request, including a value sets all the controller's hubs, unless a non null value for the attribute hub (see above) is included in the request.

locks (array[lock]) optional

The array of all locks connected to the controller.

monitors (array[monitor]) optional

The array of all door monitors connected to the controller.

readers (array[reader]) optional

The array of readers connected to this controller.

rexButtons (array[rex button]) optional

The array of Request-To-Exit (REX) buttons connected to this controller.

ioPorts (array[io port]) optional

The array of IO ports configured on this controller.

id (string) mandatory

The id of the hub.

name (string) ignored

The name of the hub.

reference (string) optional

The reference property of the hub.

doors (array[object reference]) ignored

The doors controlled by this hub.

port (number) mandatory

A number that denotes the hardware terminals assigned for this lock.

• Axis A1001: 1 for LOCK pin H1, 2 for LOCK pin H2, or 3 for RELAY|PWR/REL.

• Axis A1210: 1 for RELAY.

• Axis A1601: 1 for RELAY 1, or 2 for RELAY 2.

• Axis A1610: 1 for RELAY 1, or 2 for RELAY 2.

• Axis A9161: 1 for RELAY.

• Axis A9188: 1 for RELAY1, 2 for RELAY2,..., 8 for RELAY8.

usage (string) mandatory

One of

• PRIMARY: If the lock is the primary lock.

• SECONDARY: If the lock is the secondary lock.

mode (string) mandatory

The mapping between port behavior and locked/unlocked. One of

• ENGAGE_FAIL_SAFE: port or relay powered up when locked.

• ENGAGE_FAIL_SECURE: port or relay powered down when locked.

door (object reference) mandatory

The door this lock is connected to.

port (number) mandatory

A number that denotes the hardware terminals assigned for this monitor.

• Axis A1001: 1 for DOOR IN 1 pin IN1, or 2 for DOOR IN 2 pin IN3.

• Axis A1210: 1 for DOOR IN pin DPS.

• Axis A1601: 1 for DOOR 1 pin IO6, or 2 for DOOR 2 pin IO12.

• Axis A1610: 1 for DOOR 1 pin IO6, or 2 for DOOR 2 pin IO12.

• Axis A9161: 1 for IO4.

• Axis A9188: 1 for IO1, 2 for IO2,..., 8 for IO8.

type (string) mandatory

The operation mode of this door monitor. One of

• OPEN_CIRCUIT_OPEN_DOOR: if the door monitor circuit is open when the door is open.

• OPEN_CIRCUIT_CLOSED_DOOR: if the door monitor circuit is open when the door is closed.

door (object reference) mandatory

The door this monitor is connected to.

port (number) mandatory

A number that denotes the hardware terminals assigned for this reader.

• Axis A1001: 1 for READER DATA 1, or 2 for READER DATA 2.

• Axis A1210: 1 for READER.

• Axis A1601: 1 for READER 1, or 2 for READER 2.

• Axis A1610: 1 for READER 1, or 2 for READER 2.

• Axis A9161: Not applicable.

• Axis A9188: Not applicable.

type (string) mandatory

The type of this reader. One of

• RS485_HD_OSDP: For RS485 half-duplex and OSDP.

• WIEGAND_SINGLE_LED: For Wiegand protocol with a single LED.

• WIEGAND_DUAL_LED: For Wiegand protocol with two LEDs.

door (object reference) mandatory

The door this reader is connected to.

inside (boolean) optional

Whether the reader is mounted inside (true) or outside (false). Defaults to false.

port (number) mandatory

A number that denotes the hardware terminals assigned for this REX Button.

• Axis A1001: 1 for DOOR IN 1 pin IN2, or 2 for DOOR IN 2 pin IN4.

• Axis A1210: 1 for DOOR IN pin REX.

• Axis A1601: 1 for DOOR 1 pin IO5, or 2 for DOOR 2 pin IO11.

• Axis A1610: 1 for DOOR 1 pin IO5, or 2 for DOOR 2 pin IO11.

• Axis A9161: 1 for IO3.

• Axis A9188: Not applicable.

type (string) mandatory

The operation mode of this REX button. One of

• CLOSING_CIRCUIT_TRIGGERS: If activating the REX button closes the circuit.

• OPENING_CIRCUIT_TRIGGERS: If activating the REX button opens the circuit.

• CLOSING_CIRCUIT_TRIGGERS_NO_UNLOCK: Same as CLOSING_CIRCUIT_TRIGGERS but without unlocking.

• OPENING_CIRCUIT_TRIGGERS_NO_UNLOCK: Same as OPENING_CIRCUIT_TRIGGERS but without unlocking.

door (object reference) mandatory

The door this REX button is connected to.

port (number) mandatory

A number that denotes the hardware terminals assigned for this IO Port.

• Axis A1001: 1 or 2 for pins IO1 and IO2.

• Axis A1210: 1 or 2 for AUX I/O pins I/O 1 and I/O 2.

• Axis A1601: 1, 2, 3, 4, 13, or 14 for AUX IO pins IO1,..., IO4, and EXTERNAL pins IO13 and IO14.

• Axis A1610: 1, 2, 3, 4, 13, or 14 for AUX IO pins IO1,..., IO4, and EXTERNAL pins IO13 and IO14.

• Axis A9161: 1 or 2 for pins IO1 and IO2.

• Axis A9188: Not applicable.

type (string) mandatory

The configuration, one of

• IN_NG: Input, deactivated by grounding.

• IN_NO: Input, deactivated by leaving floating.

• OUT_NG: Output, grounded when inactive.

• OUT_NO: Output, floating when inactive.

Perform the reset or the restart actions on a controller with this request.

{
  "action": "RESET",
  "controller": {
    "id": "controller1",
    "name": "Entrance controller",
    "reference": "YYKHJV"
  }
}

action (string) mandatory

The action, one of RESET or RESTART.

controller (object reference) mandatory

The controller.

Initiate a firmware update of a controller with this request.

{
  "version": "1.60.0",
  "controller": {
    "id": "controller1",
    "name": "Entrance controller",
    "reference": "YYKHJV"
  }
}

version (string) mandatory

Identifies one of the available firmware versions by name.

controller (object reference) mandatory

The controller.

Retrieve the names of the firmware versions available per controller type with this request.

{
  "controllerType": "A1001",
  "versions": [
    "1.57",
    "1.60.0",
    "1.60.0.1"
  ]
}

controllerType (string)

Identifies the controller type for which firmware is available.

versions (array[string])

A list of names that will identify the firmware versions that are available for the controller type. This list may be empty.

Retrieve the current pin chart for a controller with this request.

Example 1

{
  "device": "Entrance Lock 1",
  "connections": [
    {
      "socket": "LOCK",
      "terminal": "-",
      "wire": "GND"
    },
    {
      "socket": "LOCK",
      "terminal": "H1",
      "wire": "OUT"
    }
  ]
}

Example 2

{
  "device": "Entrance Reader 1",
  "connections": [
    {
      "socket": "READER DATA 1",
      "terminal": "A-",
      "wire": "RX/TX B-"
    },
    {
      "socket": "READER DATA 1",
      "terminal": "B+",
      "wire": "RX/TX A+"
    },
    {
      "socket": "READER I/O 1",
      "terminal": "-",
      "wire": "GND"
    }
  ]
}

device (string)

The connected peripheral.

connections (array[connection])

How the peripheral is connected.

socket (string)

The name of the socket on the controller.

terminal (string)

The name of the terminal on the controller.

wire (string)

The description of the terminal on the peripheral.

{
  "id": "door1",
  "name": "Entrance door",
  "reference": "YYKHJV",
  "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",
    "reference": "YYKHJV"
  },
  "policies": [
    {
      "id": "policy1",
      "name": "Ground floor - office hours",
      "reference": "YYKHJV"
    },
    {
      "id": "policy2",
      "name": "Ground floor - weekends",
      "reference": "YYKHJV"
    }
  ],
  "visits": [
    {
      "id": "visit1",
      "name": "May marketing event",
      "reference": "YYKHJV"
    }
  ],
  "doorGroups": [
    {
      "id": "doorgroup1",
      "name": "Ground floor",
      "reference": "YYKHJV"
    },
    {
      "id": "doorgroup2",
      "name": "Perimeter doors",
      "reference": "HGDFFE"
    }
  ],
  "accessSeconds": 7,
  "openTooLongSeconds": 30,
  "preAlarmSeconds": 10,
  "relockMillis": 1000,
  "unlock": {
    "id": "schedule2",
    "name": "Open house hours",
    "reference": "YYKHJV"
  },
  "unlockSecondary": {
    "id": "schedule1",
    "name": "Office hours",
    "reference": "YYKHJV"
  }
  "owner": {
    "id": "sys1",
    "name": "Facility system",
    "reference": "YYKHJV"
  },
  "transfer": {
    "id": "domain2",
    "name": "Apt. 1",
    "reference": "YYKHJV"
  },
  "transferredTo": {
    "id": "sys2",
    "name": "Tenant system",
    "reference": "YYKHJV"
  },
}

If the door is transferred, some attributes can only be set from the transferring system, while some can only be set from the system receiving the transfer. These are marked "configuration", and "manage" or "manage*", respectively, below.

If the door is shared, the attributes marked "manage*", but only those, can be set from the receiving system.

Attempts to set attributes that cannot be set are ignored.

The following rules apply for the lockMode and lockStateOverride values:

1. Door.lockMode = Door.lockStateOverride if Door.lockStateOverride is not NONE,
2. else Door.lockMode = UNLOCKED if a schedule set in Door.unlock is active,
3. else Door.lockMode = LOCKED if a schedule set in Door.unlockSecondary is active,
4. else Door.lockMode = LOCKED if the door is configured with only one lock,
5. else Door.lockMode = DOUBLE_LOCKED.

The following rules apply for the doorMonitorState value:

1. CLOSED may change to OPEN or FORCED_OPEN.
2. OPEN may change to CLOSED, OPEN_TOO_LONG, or FORCED_OPEN.
3. OPEN_TOO_LONG may only change to CLOSED.
4. FORCED_OPEN may only change to CLOSED. (Will not change to OPEN_TOO_LONG regardless of how long the door has been open).

id (string) ignored

The id of the door.

name (string) mandatory [configuration]

The name of the door.

reference (string) optional [configuration]

The reference property of the door.

description (string) optional [manage]

The description of the door.

directional (boolean) optional [configuration]

Whether the door is directional (true) or not (false). Defaults to false.

lockMode (string) ignored

Determined by override, or if none, by schedule, or if none, defaults to LOCKED or DOUBLE_LOCKED depending on the controller lock configuration. One of BLOCKED, UNLOCKED, LOCKED, DOUBLE_LOCKED, or UNKNOWN.

lockState (string) ignored

One of UNLOCKED, LOCKED, DOUBLE_LOCKED, UNKNOWN, or DETACHED. The value DETACHED applies only to wireless locks and means that the controller has lost contact with the lock.

lockStateOverride (string) optional [manage]

Override the influence of schedules on the lock mode. One of:

• NONE is default and means that the door will be locked unless unlocked by a schedule.

• BLOCKED means that the door is locked and that all requests for access will be denied.

• UNLOCKED, LOCKED, DOUBLE_LOCKED: means that the lock shall always be in that state and that the attribute lockState shall have that value.

This attribute can only be set in a separate PUT request after the door has been created.

doorMonitorState (string) ignored

May be CLOSED, OPEN, OPEN_TOO_LONG, FORCED_OPEN, or UNKNOWN.

controller (controller connection) ignored

The door's controller if any. The controller is set through the controllers resource.

hub (object reference) ignored

The hub through which this door is connected to the controller, if any. The hub is set through the hubs resource.

policies (array[object reference]) optional [manage*]

The list of policies that include this door.

visits (array[object reference]) optional [manage*]

The list of visits that include this door.

doorGroups (array[object reference]) optional [manage*]

The list of door groups that this controller is a member of.

accessSeconds (number) optional [configuration]

The number of seconds a door will be accessible for after access is granted. Defaults to 0.

openTooLongSeconds (number) optional [configuration]

The number of seconds that the door has to be held open to trigger an alarm. Defaults to 0.

preAlarmSeconds (number) optional [configuration]

The number of seconds separating the pre-alarm from the door held open alarm. Defaults to 0.

relockMillis (number) optional [configuration]

Affects how long a door with door monitor stays unlocked during a granted access.

• If a door monitor has not been configured the door stays unlocked for accessSeconds (above).

• Otherwise, if relockMillis is null, the door remains unlocked until it is deemed closed by the door monitor.

• Otherwise, relockMillis is the number of milliseconds the door will remain unlocked after the door is deemed opened.

Defaults to null.

unlock (object reference) optional [manage]

A schedule defining time periods when the door shall be unlocked.

unlockSecondary (object reference) optional [manage]

A schedule defining time periods when the secondary lock (if any) shall be unlocked.

owner (object reference) ignored

The system that created the door and owns the configuration.

transfer (object reference) ignored

The domain that distributes control of the door; null if controlled by the owner.

transferredTo (object reference) ignored

The system that owns control of the door if different than the owner; otherwise null.

id (string) mandatory

The id of the controller.

name (string) ignored

The name of the controller.

connectionState (string) ignored

CONNECTED or DISCONNECTED

connectionInfo (string) ignored

Details regarding the connection state intended for human consumption.

Perform the grant access action on a door denoted by id above with this request.

A blocked door mode will result in an Unsupported Request Error. The value of the attribute 'issue' will be "BLOCKED".

An offline door will result in an Offline Error

{
  "action": "GRANT_ACCESS",
  "door": {
    "id": "door1",
    "name": "Entrance door",
    "reference": "YYKHJV"
  }
}

action (string) mandatory

Must be "GRANT_ACCESS".

door (object reference) ignored

The target door for the action.

{
  "id": "doorgroup1",
  "name": "Equipment rooms",
  "policies": [
    {
      "id": "policy1",
      "name": "Ground floor - office hours",
      "reference": "YYKHJV"
    },
    {
      "id": "policy2",
      "name": "Ground floor - weekends",
      "reference": "UREEVU"
    }
  ],
  "doors": [
    {
      "id": "door1",
      "name": "Server room",
      "reference": "YYKHJV"
    },
    {
      "id": "door2",
      "name": "HVAC room",
      "reference": "GSQRMN"
    }
  ]
}

id (string) ignored

The id of the door group.

name (string) mandatory

The name of the door group.

reference (string) optional

The reference property of the door group.

policies (array[object reference]) optional

The polices that include this door group.

doors (array[object reference]) optional

The doors included in this door group.

Parameters:

• offset - (number) Controls the results starting point by position.

• before - (id) Controls the results ending point relative an event.

• after - (id) Controls the results starting point relative an event.

• limit - (number) This parameter limits the maximum number of events to be retrieved.

• mintime - (number) Controls the results ending point by log time in milliseconds since the epoch.

• maxtime - (number) Controls the results starting point by log time in milliseconds since the epoch.

• token - (id) Retrieve events that involve the token with this id only.

• user - (id) Retrieve events that involve the user with this id only.

• method - (string) Retrieve events that were caused by a method of a particular type only.

• reason - (string list) Retrieve events that are of the reasons provided only. Multiple values may be specified, separated by commas.

• door - (id list) Retrieve events that involve the door with these ids only. Multiple values may be specified, separated by commas.

• extended - (any value) Turns on the extended version of the request. Responses to requests without this parameter will exclude events, as specified further below, unless specifically included through the reason parameter.

All query parameters are optional and provide filtering of the events retrieved.

The response is always ordered from newer to older. Parameters "offset", "before" and "after" are mutually exclusive; only one can be used in the same request.

The names of the parameters "before" and "after" may be confusing. They refer to the events positions in the results, not on the time line.

Examples:

If a total of 100 events exist, IDs 1 to 100 where 1 is the oldest and 100 is the newest, then:

• limit = 4 will return events 100, 99, 98, and 97; the 4 most recent events.

• offset = 2 & limit = 1 will return the event 98; the third most recent event.

• before = 99 will return events 100; all events newer than the event with id 99.

• after = 99 & limit = 2 will return events 98 and 97; the newest 2 events older than the event with id 99.

Example 1

  {
    "id": "event4",
    "command": null,
    "logTime": 1468577500000,
    "method": "CARD",
    "reason": "ACCESS",
    "info": null,
    "token": {
      "id": "token1",
      "name": "Alice's card",
      "reference": "YYKHJV"
    },
    "user": {
      "id": "user1",
      "name": "Alice Smith",
      "reference": "YYKHJV"
    },
    "policy": {
      "id": "policy1",
      "name": "Ground floor - office hours",
      "reference": "YYKHJV"
    },
    "door": {
      "id": "door1",
      "name": "Entrance door",
      "reference": "YYKHJV"
    },
    "controller": {
      "id": "controller1",
      "name": "Entrance door controller",
      "reference": "YYKHJV"
    },
    "trigger": null
  }

Example 2

  {
    "id": "event3",
    "command": null,
    "logTime": 1468577600000,
    "method": "REX",
    "reason": ACCESS,
    "info": null,
    "token": null,
    "user": null,
    "policy": null,
    "door": {
      "id": "door1",
      "name": "Entrance door",
      "reference": "YYKHJV"
    },
    "controller": {
      "id": "controller1",
      "name": "Entrance door controller",
      "reference": "YYKHJV"
    },
    "trigger": null
  }

Example 3

  {
    "id": "event2",
    "command": null,
    "logTime": 1468577700000,
    "method": "CARD",
    "reason": "DENY_UNRECOGNIZED_CARD",
    "info": "AABBCCDDEE",
    "token": null,
    "user": null,
    "policy": null,
    "door": {
      "id": "door1",
      "name": "Entrance door"
    },
    "controller": {
      "id": "controller1",
      "name": "Entrance door controller",
      "reference": "YYKHJV"
    },
    "trigger": null
  }

Example 4

  {
    "id": "event1",
    "command": {
      "id": "command1",
      "name": "Release entrance door",
      "reference": "YYKHJV"
    },
    "logTime": 1468577800000,
    "method": "COMMAND",
    "reason": "OVERRIDE_CANCELED",
    "info": null,
    "token": null,
    "user": null,
    "policy": null,
    "door": {
      "id": "door1",
      "name": "Entrance door",
      "reference": "YYKHJV"
    },
    "controller": {
      "id": "controller1",
      "name": "Entrance door controller",
      "reference": "YYKHJV"
    },
    "trigger": {
      "id": "trigger1",
      "name": "Close down",
      "reference": "YYKHJV"
    }
  }

id (string)

The id of the event.

command (object reference)

Command involved in the event if applicable.

logTime (number)

The time of the event as milliseconds since the epoch.

method (string)

The origin of the event, one of: API, API_1, API_2, CARD, CARD_PIN, DOOR, SITE, COMMAND, PIN, REMOTE, REX, SCHEDULE, TRIGGER, UNDEFINED, or URL. The value API denotes the method called "Officer" in the Access Manager UI.

reason (string)

The reason for the event.

• ACCESS access requested and granted.

• ACCESS_UNAUTHORIZED currently unauthorized access requested but granted.

• DENY_UNREACHABLE access requested but communication with the controller failed.

• DENY_READ_ERROR access requested but we couldn't make sense of the token.

• DENY_UNRECOGNIZED_TOKEN access requested but the presented card ID has not been registered.

• DENY_AUTHORIZED currently authorized acces+uested but denied.

• DENY_UNAUTHORIZED [older events only] access requested but has not been authorized.

• DENY_TOKEN_BLOCKED access requested but the token's blocked attribute is true.

• DENY_NO_USER access requested but the token is not assigned to user.

• DENY_USER_BLOCKED access requested but the token user's blocked attribute is true.

• DENY_INVALID_PIN_ONLY only a PIN was entered and it did not match the PIN of any user.

• DENY_PIN_MISMATCH access required a pin in addition to a card and it was not entered correctly.

• DENY_NO_AUTHORIZATION access requested but the user has no valid authorizations.

• DENY_NO_POLICY access requested but the valid authorizations have no policy for the door.

• DENY_NO_SCHEDULE access requested but the valid authorization's policies for the door are off schedule.

• ALERT_BATTERY a peripheral has indicated that it needs its battery checked.

• ALERT_DOOR_OPEN_TOO_LONG the door was left open for too long.

• ALERT_DOOR_FORCED_OPEN the door was forced open.

• ALERT_CONTROLLER_TAMPER the cover of the controller was removed.

• ALERT_JAMMED a peripheral has indicated that it is jammed.

• ALERT_RADIO the signal was lost to a wireless peripheral.

• ALERT_READER_DISCONNECTED a reader was disconnected.

• ALERT_READER_MOVED a reader was physically moved.

In addition, when the 'extended' parameter is included in the request:

• ALERT_CONTROLLER_DISCONNECTED the connection to the controller was lost.

• ALERT_CONTROLLER_CONNECTED the connection to the controller was regained.

• ALERT_CONTROLLER_RESET the controller was reset through Access Manager.

• COMMAND a command was issued.

• COMMAND_DONE a command finished successfully.

• COMMAND_FAILED a command finished unsuccessfully.

• CONTROLLER_RESTARTED the controller was restarted through Access Manager.

• DENY_DOOR_BLOCKED access requested through a reader was denied because the door was blocked.

• DOOR_CLOSED the door was closed.

• DOOR_OPENED the door was opened.

• OVERRIDE_TO_DOUBLE_LOCKED the lock mode was overridden to double locked state.

• OVERRIDE_TO_LOCKED the lock mode was overridden to locked state.

• OVERRIDE_TO_UNLOCKED the lock mode was overridden to unlocked state.

• OVERRIDE_CANCELED lock mode overridden was canceled.

• STATE_DOUBLE_LOCK the door entered the double locked state.

• STATE_LOCK the door entered the locked state.

• STATE_UNLOCK the door entered the unlocked state.

• TRIGGER_DENIED_CREDENTIAL trigger denied because the required credentials were not presented.

• TRIGGER_DENIED_DEVICE_BLOCKED trigger denied because the device was blocked.

• TRIGGER_DENIED_DOOR trigger denied because the door requirement of the trigger was not fulfilled.

• TRIGGER_DENIED_INVALID_PIN_ONLY trigger denied because only a PIN was entered and it did not match the PIN of any user.

• TRIGGER_DENIED_NO_USER trigger denied because the device has no user user.

• TRIGGER_DENIED_PIN_MISMATCH trigger denied by card+PIN authentication because the entered PIN is not the user's.

• TRIGGER_DENIED_ROLE trigger denied because the role requirement of the trigger was not fulfilled.

• TRIGGER_DENIED_SCHEDULE trigger denied because the trigger was inactive by schedule.

• TRIGGER_DENIED_UNRECOGNIZED_TOKEN trigger denied by card authentication because the card is not recognized.

• TRIGGER_DENIED_USER_BLOCKED trigger denied because the user is blocked.

• TRIGGER_GRANTED trigger granted and its commands issued.

Note that whether an event will occur for a particular reason will occur is subject to controller and peripheral types and configurations.

info (string)

Holds the card ID as read by the controller if reason is DENY_UNRECOGNIZED_TOKEN.

token (object reference)

Token involved in the event if applicable.

user (object reference)

User involved in the event if applicable.

policy (object reference)

Policy involved in the event if applicable.

door (object reference)

Door involved in the event if applicable.

controller (object reference)

Controller involved in the event if applicable.

trigger (object reference)

Trigger involved in the event if applicable.

{
  "id": "hub1",
  "name": "Entrance hub",
  "reference": "YYKHJV",
  "description": "The hub connected to the entrance controller",
  "type": "INTEGO""ipAddress": "192.168.1.43""deviceAddress": "0x00000100",
  "controller": {
    "id": "controller1",
    "name": "Entrance controller",
    "reference": "YYKHJV"
  },
  "doors": [
    {
      door: {
        "id": "door2",
        "name": "Inner entrance door 2",
        "reference": "YYKHJV"
      },
      lockId: "0x00000200",
      monitorId: "00E8E3F"
    },
    {
      door: {
        "id": "door3",
        "name": "Inner entrance door 3",
        "reference": "YYKHJV"
      },
      lockId: "0x00000300",
      monitorId: "00F24KM"
    }
  ]
}

id (string) ignored

The id of the hub.

name (string) mandatory

The name of the hub.

reference (string) optional

The reference property of the hub.

description (string) optional

The description of the hub.

type (string) mandatory

One of APERIO and INTEGO.

ipAddress (string) optional

Hub IP address, needed for INTEGO.

deviceAddress (string) optional

Hub device address, needed for INTEGO.

controller (object reference) ignored

The controller to which the hub is allocated.

doors (array[hub door reference]) optional

The doors allocated to this hub.

door (object reference) mandatory

The door.

lockId (string) mandatory

The lock id (a.k.a. Device address).

monitorId (string) mandatory

The monitor id (a.k.a. Phi string).

For managing the registration of controllers connected via the One-Click Connection Component (O3C). Creating the resource registers the controller with O3C, and deleting the resource unregisters the controller.

This resource is immutable and there can be only be one per controller. To change the registration, the existing resource must be deleted before creating a new one with the new details.

{
  "mac": "556677889900",
  "oak": "yuiwe87yuqqoiee"
}

mac (string) mandatory

The MAC of the controller.

oak (string) mandatory

The OAK for the controller.

"Policies" are known as "Privileges" in the Access Manager UI.

{
  "id": "policy1",
  "name": "General access",
  "reference": "YYKHJV",
  "credential": "CARD",
  "owner": {
    "id": "sys1",
    "name": "Acme",
    "reference": "YYKHJV"
  },
  "resolution": "REGULAR",
  "schedule": {
    "id": "schedule1",
    "name": "Office hours",
    "reference": "YYKHJV"
  },
  "authorizations": [
    {
      "id": "authorization1",
      "name": "Janitor",
      "reference": "YYKHJV"
    },
    {
      "id": "authorization2",
      "name": "Manager",
      "reference": "SXHERT"
    }
  ],
  "doors": [
    {
      "id": "door1",
      "name": "Entrance",
      "reference": "YYKHJV"
    },
    {
      "id": "door2",
      "name": "Server room",
      "reference": "PHPTRS"
    }
  ],
  "doorsInside": [
    
  ],
  "doorsOutside": [
    
  ],
  "doorGroups": [
    {
      "id": "doorgroup1",
      "name": "Ground floor",
      "reference": "YYKHJV"
    },
    {
      "id": "doorgroup2",
      "name": "Equipment rooms",
      "reference": "PWUDTR"
    }
  ]
}

id (string) ignored

The id of the policy.

name (string) mandatory

The name of the policy.

reference (string) optional

The reference property of the policy.

credential (string) mandatory

The type of credential that may be used to gain access. One of

• CARD: Only a card is required.

• CARD_PIN: Both a card and a PIN is required.

• PIN: Only a PIN is required.

• REMOTE: Telcred Personal is required.

• API_1 or API_2: An API request to access is required. See Request Access by User ID.

owner (object reference) ignored

The system that created the policy. Never null.

resolution (string) optional

Offers control over where the access grant/deny decision is taken. One of

• LOCK: If possible, the access grant/deny decision is taken by the lock itself.

• REGULAR: The access grant/deny decision is taken by the controller or/and in the cloud.

Defaults to REGULAR.

schedule (object reference) optional

A schedule defining time periods where the policy is effective. None (null) means always.

authorizations (array[object reference]) optional

The list of authorizations that has this policy.

doors (array[object reference]) optional

The list of doors for which this policy applies to access from both inside and outside.

doorsInside (array[object reference]) optional

The list of doors for which this policy applies to access from the inside.

doorsOutside (array[object reference]) optional

The list of doors for which this policy applies to access from the outside.

doorGroups (array[object reference]) optional

The list of door groups for which this policy applies to access from both inside and outside.

Setting resolution to LOCK specifies that the access grant/deny decision is, if possible, to be taken by the lock itself rather than by the controller or in the cloud. Specifically for SimonsVoss wireless locks, this is realized using its onboard whitelist.

Setting resolution to LOCK imposes the following limitations:

• The policy's credential property must be set to CARD.

• The policy's schedule property must be set to null.

• The number of eligible cards must not exceed 250 per lock.

Exceeding the limit of 250 will cause the resolution to be performed on the controller.

A door is only included once, either in doors, doorsInside, or doorsOutside. In requests, multiple inclusions of a door in doors, doorsInside, and doorsOutside, are resolved additively. For example

• doors: [a, b],

• doorsInside: [b , c],

• doorsOutside: [c, d]

is equivalent to

• doors: [a, b, c],

• doorsInside: [],

• doorsOutside: [d].

When a request only updates some of these values they are first replaced completely, where after they are combined with the unchanged values. For example where

• doors: [a],

• doorsInside: [b],

• doorsOutside: [c]

An update with only doorsInside: [a], results in

• doors: [a],

• doorsInside: [],

• doorsOutside: [c].

Or an update performed with only doors: [c], results in

• doors: [c],

• doorsInside: [b],

• doorsOutside: [].

{
  "authorization": {
    "id": "authorization1",
    "name": "IT Technician",
    "reference": "YYKHJV"
  },
  "cid": "456678768",
  "credentials": [
    "CARD",
    "CARD_PIN"
  ],
  "door": {
    "id": "door1",
    "name": "Entrance door",
    "reference": "YYKHJV"
  },
  "granted": false,
  "pin": "1111",
  "policy": {
    "id": "policy1",
    "name": "Ground floor - office hours",
    "reference": "YYKHJV"
  },
  "reason": "DENY_PIN_MISMATCH",
  "token": {
    "id": "token1",
    "name": "Alice's card",
    "reference": "YYKHJV"
  },
  "user": {
    "id": "user1",
    "name": "Alice Smith",
    "reference": "YYKHJV"
  }
}

In the request, most of the attributes are ignored.

If there are no errors, the response will have status code 200 and document the outcome of the request to access. Note that this will be the case regardless of whether access was granted or denied.

By Token CID

Request access for a token specified by CID. In the request the attribute "cid" is mandatory and the attribute "pin" is optional. The remaining attributes are only relevant to the response.

By Token ID

Request access for a token specified by ID. In the request the attribute "pin" is optional and the remaining attributes are only relevant to the response.

By User PIN

Request access for a user specified by PIN. If the PIN matches several users access will be granted unless denied for all. In the request the attribute "pin" is mandatory and the remaining attributes are only relevant to the response.

By User ID

Request access for a user specified by ID. Only policies that allow credentials API_1 or API_2 can match this request. In the request the attribute "credentials" is mandatory. The value may be a list of either "API_1", or "API_2", or both. The remaining attributes are only relevant to the response.

authorization (object reference) ignored

One (of possibly several) matching authorizations; or null if none.

cid (string) mandatory or optional

The token CID.

credentials (array[string]) mandatory or ignored

A list of the considered credentials; policies must match at least one.

• By User ID action: (mandatory) One or both of API_1 and API_2.

• Other actions: (ignored) One or both of CARD and CARD_PIN.

door (object reference) ignored

The door for which access is requested.

granted (boolean) ignored

Set to true if access was granted, false otherwise.

pin (string) mandatory or optional

The PIN used if any; otherwise null.

policy (object reference) ignored

One (of possibly several) matching policies; or null if none.

reason (string) ignored

The reason for a denied request. See events for a list of possible values.

token (object reference) ignored

The token that matches the CID, or null if none.

user (object reference) ignored

The user of the token that matches the CID, or null if none.

{
  "id": "schedule1",
  "name": "Office hours",
  "reference": "YYKHJV",
  "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",
      "reference": "YYKHJV"
    }
  ],
  "doors": [
    {
      "id": "door1",
      "name": "Entrance door",
      "reference": "YYKHJV"
    }
  ]
}

The schedule defines a set of time periods through the attributes include and exclude according to these rules:

• Only time periods covered by include attribute are in the set.

• Time periods covered by the exclude attribute are not in the set, regardless.

The internal structure of attributes include and exclude are identical: A set of once items, a set of weekly items, and a set of yearly items. The coverage of each attribute is the union of the coverage of the attributes items.

Each Once item covers a single time interval. Attributes:

• from: The first second to be included on the format yyyy-MM-ddTHH:mm:ss, e.g. 2017-11-23T00:00:00.

• to: The last second to be included in the interval denoted as above.

Example: {"from": "2017-12-31T00:00:00", "to": "2017-12-31T23:59:59"} is the whole day, 2017-12-31.

Each Weekly item covers from one time of day to a second time of day, one or more weekdays, recurring weekly but limited by a first and a last date. Attributes:

• from: The first second to be included on a daily basis in the format HH:mm:ss, e.g. 13:00:00.

• to: The last second to be included on a daily basis denoted as above.

• days: A list of the covered weekdays denoted as MO, TU, WE, TH, FR, SA, and SU.

• start: The first day of coverage as a date, in the format yyyy-MM-dd, e.g. 2017-01-01.

• end: The last day of coverage as a date, denoted as above.

E.g. {"from": "00:00:00", "to": "23:59:59", "days": ["SU"], "start": "2017-01-01", "end": "2017-01-08"} is all of Sunday 2017-01-01 and all of Sunday 2017-01-08.

Each Yearly item covers one time interval recurring yearly. Attributes:

• from: The first second to be included on a yearly basis, in the format --MM-ddTHH:mm:ss, e.g. --11-23T00:00:00.

• to: The last second to be included on a yearly basis, denoted as above.

E.g. {"from": "--12-01T00:00:00", "to": "--12-31T23:59:59"} is all of December every year.

The following notation is used for the formats above:

• yyyy = four-digit year

• MM = two-digit month (01=January, etc.)

• dd = two-digit day of month (01 through 31)

• HH = two digits of hour (00 through 23; weekly, see below)

• mm = two digits of minute (00 through 59)

• ss = two digits of second (00 through 59)

Note that time intervals are closed, e.g. from 12:00:00 to 12:00:01 is two seconds, and from 2017-01-01 to 2017-01-02 is two days as well as is from --01-01 to --01-02.

id (string) ignored

The id of the schedule.

name (string) mandatory

The name of the schedule.

reference (string) optional

The reference property of the schedule.

description (string) optional

The description of the schedule.

include (schedule time set) optional

Time periods that are in the set unless excluded.

exclude (schedule time set) optional

Time periods that are not in the set although included.

policies (array [object reference]) ignored

All policies using this schedule.

doors (array [object reference]) ignored

All doors using this schedule.

once (array [schedule time once]) optional

A single time interval.

weekly (array [schedule time weekly]) optional

Time interval recurring weekly.

yearly (array [schedule time yearly]) optional

Time interval recurring yearly.

from (string) mandatory

The first second to be included on the format yyyy-MM-ddTHH:mm:ss.

to (string) mandatory

The last second to be included on the format yyyy-MM-ddTHH:mm:ss.

from (string) mandatory

The first second to be included on a daily basis in the format HH:mm:ss, e.g. 13:00:00.

to (string) mandatory

The last second to be included on a daily basis in the format HH:mm:ss, e.g. 13:00:00

days (array[string]) mandatory

A list of the included weekdays denoted as MO, TU, WE, TH, FR, SA, and SU. E.g. ["SA","SU"].

start (string) mandatory

The first day to be included as a date, in the format yyyy-MM-dd, e.g. 2017-01-01.

end (string) mandatory

The last day to be included as a date, in the format yyyy-MM-dd, e.g. 2017-01-01.

from (string) mandatory

The first second to be included on a yearly basis, in the format --MM-ddTHH:mm:ss.

to (string) mandatory

The last second to be included on a yearly basis, in the format --MM-ddTHH:mm:ss

"Tokens" are known as "Devices" in the Access Manager UI.

{
  "id": "token5",
  "name": "Cindy's card",
  "reference": "YYKHJV",
  "description": "White with red print.",
  "type": "CID",
  "cid": "AABBCCDDEE",
  "blocked": false,
  "registrationCode": "h212jkj3H",
  "user": {
    "id": "user4",
    "name": "Cindy Smith",
    "reference": "YYKHJV"
  },
  "userFrom": null,
  "userTo": "2017-06-25T17:30:00"
}

id (string) ignored

The id of the token.

name (string) mandatory

The name of the token.

reference (string) optional

The reference property of the token.

description (string) optional

A description of the token.

type (string) mandatory

One of

• CID the token is a card and will be identified by its raw id.

• CNR the token is a card and will be identified by its number derived from the raw id.

cid (string) optional

The card ID or card number.

blocked (boolean) optional

true if the token is blocked. Defaults to false.

registrationCode (string) ignored

Always null. This attribute is obsolete and remains only for backwards compatibility.

user (array[object reference]) optional

The user this token is bound to.

userFrom (string) optional

The first second of the binding to the user, on the format yyyy-MM-ddTHH:mm:ss, e.g. 2017-11-23T00:00:00, in the time zone of the controller. Defaults to unlimited.

userTo (string) optional

The last second of the binding to the user denoted as above. E.g. {"user":{"id": "user4"}, "userFrom": "2017-12-31T00:00:00", "userTo": "2017-12-31T23:59:59"} will bind the token to user id user4 for the whole day, 2017-12-31, in the time zone of the controller. Defaults to unlimited.

"Users" refers to people with tokens which can open doors. This does not include administrators of the account.

{
  "id": "user4",
  "name": "Cindy Jones",
  "reference": "YYKHJV",
  "authorizations": [
    {
      "id": "authorization1",
      "name": "Janitor",
      "reference": "YYKHJV"
    },
    {
      "id": "authorization2",
      "name": "Manager",
      "reference": "YYKHJV"
    }
  ],
  "blocked": true,
  "emailAddress": "cindy@telcred.com",
  "from": null,
  "mobileEnabled": true,
  "notes": "Card received.",
  "phoneNumber": "+46123456789",
  "pin": "12345",
  "to": "2017-06-25T17:30:00",
  "tokens": [
    {
      "id": "token1",
      "name": "Card 01",
      "reference": "YYKHJV"
      "userFrom": null,
      "userTo": null
    }
  ]
}

id (string) ignored

The id of the user.

name (string) mandatory

The name of the user.

reference (string) optional

The reference property of the user.

authorizations (array[object reference]) optional

The authorizations of this user.

blocked (boolean) optional

true if the user is blocked. Defaults to false.

emailAddress (string) optional

The email address of this user.

from (string) optional

The first second of the validity period on the format yyyy-MM-ddTHH:mm:ss, e.g. 2017-11-23T00:00:00, in the time zone of the controller. Defaults to unlimited.

mobileEnabled (boolean) optional

If true, mobile access is enabled for this user. Defaults to true.

notes (string) optional

Arbitrary text.

phoneNumber (string) optional

The phone number of this user.

pin (string) optional

The PIN of the user. Limited to at most 9 characters.

to (string) optional

The last second of the validity period denoted as from above. E.g. {"from": "2017-12-31T00:00:00", "to": "2017-12-31T23:59:59"} makes the user valid for the whole day, 2017-12-31, in the time zone of the controller. Defaults to unlimited.

tokens (array[token binding]) optional

Tokens bound to the user.

id (string) mandatory

The id of the token.

name (string) ignored

The name of the token.

reference (string) optional

The reference property of the token.

userFrom (string) optional

The first second of the binding to the user. See token.

userTo (string) optional

The last second of the binding to the user. See token.

{
  "id": "visit1",
  "name": "May marketing event",
  "reference": "YYKHJV",
  "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",
    "reference": "YYKHJV"
  },
  "doors": [
    {
      "id": "door1",
      "name": "Entrance",
      "reference": "YYKHJV"
    }
  ]
}

id (string) ignored

The id of the visit.

name (string) mandatory

The name of the visit.

reference (string) optional

The reference property of the visit.

description (string) optional

The description of the visit.

credential (array[string]) (string) mandatory

The type of credential used to gain access. One or both of PIN and URL. E.g. ["PIN", "URL"].

validFrom (string) optional

The first second of validity on the format yyyy-MM-ddTHH:mm:ss, e.g. 2017-11-23T00:00:00, in the time zone of the controller. Defaults to unlimited.

validTo (string) optional

The last second of validity on the format yyyy-MM-ddTHH:mm:ss, e.g. 2017-11-23T00:00:00, in the time zone of the controller. Defaults to unlimited.

pin (string) optional

The visit PIN. Defaults to empty (no PIN).

url (string) optional

The visit URL. Defaults to empty (no URL).

schedule (object reference) optional

A schedule defining time periods when the visit applies. None (null) means always.

doors (array[object reference]) optional

The list of doors for which this visit applies.

Status code 400 is used for all error responses. The body of the response will be a JSON object (application/json) with the following attributes.

type (string)

One of MISSING, CONFLICT,... as documented below.

issue (string)

A parameter intended for programmatic consumption.

info (string)

A message intended for human consumption.

An error with type set to MISSING is returned if no object of the requested type can be found for the id parameter. The attribute 'issue' will supply the id.

{
    "type": "MISSING",
    "issue": "user2",
    "info": "There exists no user with the id user2."
}

An error with type set to MISSING is returned if one or more of the specified object references do not exist. In this case the attribute 'issue' will hold one of the missing ids.

{
    "type": "MISSING",
    "issue": "user2",
    "info": "There exists no user with the id user2."
}

An error with type set to CONFLICT is returned if a name is already in use. In this case the attribute 'issue' will hold the conflicting name.

{
    "type": "CONFLICT",
    "issue": "IT technician",
    "info": "There already exists an authorization with the name IT technician."
}

An error with type set to UNAUTHORIZED is returned if the credentials supplied through HTTP Basic Auth do not match an officer with administration privileges. The attribute issue will hold the username part of the credentials regardless of whether the issue is with the username or with the password.

{
    "type": "UNAUTHORIZED",
    "issue": "BadCop"
    "info": "Sign in failed for 'BadCop'."
}

An error with type set to METHOD is returned if the method of the request (GET/PUT/...) is not applicable to the resource given by the path of the request.

{
    "type": "METHOD",
    "issue": null
    "info": "The method (GET/PUT/POST/DELETE) is not defined for this resource."
}

An error with type set to PATH is returned if the path of the request is not recognized.

{
    "type": "PATH",
    "issue": null
    "info": "This resource is not defined."    
}

An error with type set to UNSUPPORTED is returned if the request cannot be fulfilled due to a dynamic or static constraint.

{
    "type": "UNSUPPORTED",
    "issue": "BLOCKED"
    "info": "Access cannot be granted because this door is blocked."    
}

An error with type set to CONNECTION is returned if the request cannot be fulfilled due a door/controller being offline. The attribute 'issue' will hold the id of the controller.

{
    "type": "CONNECTION",
    "issue": "controller1",
    "info": "The controller is offline."
}

An error with type set to VALUE is returned if the values provided for any of the attributes in a request are invalid. The attribute 'issue' will hold the invalid value.

{
    "type": "VALUE",
    "issue": "WIEGAND_TRIPLE_LED",
    "info": "'WIEGAND_TRIPLE_LED' is not recognized as a valid type for a reader."
}

An error with type set to O3C is returned if the details provided for the registration are incorrect or if a registration for this controller already exists.

{
    "type": "O3C",
    "issue": "controller1",
    "info": "There already exists a registration for the controller with id controller1"
}