Access Control List (ACL) API

The Access Control List (ACL) API manages access control lists. It is composed of a userId, and a list of locks the user can open, together with a few other information.

The Access Control List API supports basic CRUD operations including GET (get all, get by ID), POST, PUT and DELETE.

Definition

An ACL has a unique id, and is composed of an array of users, an array of locks, and an attribute called user_data for the caller to put whatever else they want to send.

Name		Type	Description
id		UUID v4	Unique id of the ACL.
customer		String	The customer this ACL belongs to.
users		Array of JSON Objects	Definition of each element follows.
	user_id	Number	Unique id of the user. OKMs expect the invue id.
	pin_hash	Alphanumerical string	Hash of the PIN as expected by an OKM
	auth_time	Number	Number of hours for which the key is valid. Sometimes also known as Shift Length. {1, 4, 8, 12, 24}
	sounder	Boolean	If the user has Restricted Mode enabled or not.
	sounder_delay	Number	Number of seconds before the key starts to beep. [0, 120]
	sounder_duration	Number	Number of seconds for which the key will beep. [0, 255]
	sounder_volume	Number	Volume of the beep. 0=off, 1=low, 2=normal
	permissions	Array of numbers	An array of numbers where each is a permission on a lock as: 0 = no access 1 = has access 17 = dual auth The length of the array must match the length of the locks array in this ACL. Each value is matched to the corresponding lock at the same index in the locks array.
locks		Array of serial numbers	An array of the serial numbers of the locks in the OKM. The array must be in ascending order of serial numbers. The length of the array is expected to match the permissions array of each user element of the users array of this ACL.
user_data		JSON	A JSON of values free for the customer to fill.

POST

Create an Access Control List

To create an ACL, send a POST request to the ACL endpoint.

Overwriting Existing ACLs: If an ACL with the same id already exists, sending a POST request with the same id will overwrite the existing ACL with the new data provided in the request.

POST https://domain.name/api/v1/acls/

Example request:

POST https://domain.name/api/v1/acls/ HTTP/1.1
Authorization: {{JwtReadCreateAuthorization}}
Content-Type: application/json

{
  "id": "access_control_list_1",
  "customer": "invu",
  "users": [
    {
      "user_id": 1,
      "pin_hash": "edc6f6aee2c323105cba0389d914f0a6b9e6980516df4fa31736fdc8ecac67a9",
      "auth_time": 8,
      "sounder": false,
      "sounder_delay": 10,
      "sounder_duration": 255,
      "sounder_volume": 0,
      "permissions": [0, 1, 17]
    },
    {
      "user_id": 2,
      "pin_hash": "24fb82643120b8f385b528130fac187171ab6afca1b61710ae60cb036309f4a6",
      "auth_time": 8,
      "sounder": false,
      "sounder_delay": 10,
      "sounder_duration": 255,
      "sounder_volume": 0,
      "permissions": [1, 0, 17]
    }
  ],
  "locks": ["9998765432", "9998765433", "9998765434"],
  "user_data": {
    "label": "placehoder",
    "message": "placeholder"
  },
  "okm_id": "okm_1"
}

Where:

Field		Type	Description
id		string	Unique id of the ACL. It is used as the identifier when referenced in other API calls. This ID must be unique.
customer		string	The customer this ACL belongs to.
users		array of JSON	Elements defined in the following rows.
	user_id	number	Invue ID of the user. It is numerical and has a max length of 9 digit.
	pin_hash	string	Hash of the PIN as expected by an OKM.
	auth_time	number	Number of hours the key is valid for. (1, 4, 8, 24)
	sounder	boolean	If the user has Restricted Mode enabled or not.
	sounder_delay	number	Number of seconds before the key starts to beep.
	sounder_duration	number	Number of seconds for which the key will beep.
	sounder_volume	number	Volume of the beep.
	permissions	array of numbers	Each element of the array is a permission on the lock at the same index in the locks array of the ACL.
locks		array of strings	An array of the serial numbers of the locks in the OKM.
user_data		object	This is a field where the implementer can store app related information. The OKM Service does not use this data. This data is returned when the ACL is fetched from the API. This is optional.
okm_id		string	The id of the OKM that this ACL is associated with. (Optional)

The okm_id value is optional. If it is present, the ACL will be linked to the OKM, if the OKM exists. If the okm_id value is present but the OKM does not exist, the ACL will be not be created, and an error will be returned.

Example response:

HTTP/1.1 201 OK
Content-Type: application/json; charset=utf-8

{
  "message": "Resource created successfully",
  "data": {
    "id": "access_control_list_1",
    "customer": "invu",
    "users": [
      {
        "user_id": 1,
        "pin_hash": "edc6f6aee2c323105cba0389d914f0a6b9e6980516df4fa31736fdc8ecac67a9",
        "auth_time": 8,
        "sounder": false,
        "sounder_delay": 10,
        "sounder_duration": 255,
        "sounder_volume": 0,
        "permissions": [0, 1, 17]
      },
      {
        "user_id": 2,
        "pin_hash": "24fb82643120b8f385b528130fac187171ab6afca1b61710ae60cb036309f4a6",
        "auth_time": 8,
        "sounder": false,
        "sounder_delay": 10,
        "sounder_duration": 255,
        "sounder_volume": 0,
        "permissions": [1, 0, 17]
      }
    ],
    "locks": ["9998765432", "9998765433", "9998765434"],
    "user_data": {
      "label": "placehoder",
      "message": "placeholder"
    }
  }
}

Possible errors

Error Code	Description
400 Bad Request	Error: Error in creating access control list error: duplicate key value violates unique constraint “acl_id_customer_key” and “customer_name”
403 Forbidden	{ "error_code": "UNAUTHORIZED_ACCESS", "error_msg": "Missing required scopes" }

GET

Get all access lists for a customer

To fetch the ACLs for a customer, send a GET request to the /acls endpoint. This will return an array of ACL objects for the specified customer. The default pagination is 30 records per request.

GET https://domain.name/api/v1/acls?customer={customer}

Example request:

POST https://domain.name/api/v1/acls/ HTTP/1.1
Authorization: {{JwtReadAuthorizationToken}}

Example response:

{
  "message": "Resource fetched successfully",
  "pagination": {
    "page": 1,
    "results_per_page": "30",
    "total_results": "5"
  },
  "data": [
    {
      "id": "access_control_list_1",
      "customer": "invu",
      "users": [
        {
          "user_id": 1,
          "pin_hash": "edc6f6aee2c323105cba0389d914f0a6b9e6980516df4fa31736fdc8ecac67a9",
          "auth_time": 8,
          "sounder": false,
          "sounder_delay": 10,
          "sounder_duration": 255,
          "sounder_volume": 0,
          "permissions": [0, 1, 17]
        },
        {
          "user_id": 2,
          "pin_hash": "24fb82643120b8f385b528130fac187171ab6afca1b61710ae60cb036309f4a6",
          "auth_time": 8,
          "sounder": false,
          "sounder_delay": 10,
          "sounder_duration": 255,
          "sounder_volume": 0,
          "permissions": [1, 0, 17]
        }
      ],
      "locks": ["9998765432", "9998765433", "9998765434"],
      "user_data": {
        "label": "placehoder",
        "message": "placeholder"
      }
    },
    {
      "id": "access_control_list_42",
      ...
    },
      ...    
  ]
}

Get ACLs for a customer, with pagination

The default pagination is 30 record per request.

Example request:

GET https://domain.name/api/v1/acls?customer={customer}&page=2&results_per_page=10

Authorization: {{JwtReadAuthorizationToken}}

Where:

parameter	description
customer	The name of the customer that owns the acls
page	The starting page number
results_per_page	The number of results per page

Example response will be the same as above.

Get one specific ACL

Sending a get to the access-control-list endpoint will get one access control list object for the customer.

GET https://domain.name/api/v1/acls/access_control_list_1?customer={customer}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "message": "Resource fetched successfully",
  "data": {
    "id": "access_control_list_1",
    "customer": "invu",
    "users": [
      {
        "user_id": 1,
        "pin_hash": "edc6f6aee2c323105cba0389d914f0a6b9e6980516df4fa31736fdc8ecac67a9",
        "auth_time": 8,
        "sounder": false,
        "sounder_delay": 10,
        "sounder_duration": 255,
        "sounder_volume": 0,    
        "permissions":[0,1,17]
      } ,
      {
        "user_id": 2,
        "pin_hash": "24fb82643120b8f385b528130fac187171ab6afca1b61710ae60cb036309f4a6",
        "auth_time": 8,
        "sounder": false,
        "sounder_delay": 10,
        "sounder_duration": 255,
        "sounder_volume": 0,
        "permissions":[1,0,17]
      }
    ],
    "locks": ["9998765432", "9998765433", "9998765434"],
    "user_data": {
      "label": "placehoder",
      "message": "placeholder"
    }
  }
}

Possible errors

Error Code	Description
403 Forbidden	{ "error_code": "UNAUTHORIZED_ACCESS", "error_msg": "Missing required scopes" }
404 Not Found	Error: Access control list not found
400 Bad Request	Error: Error in updating access control list error: duplicate key value violates unique constraint “acl_id_customer_key” and "customer_name"

PUT

Update an ACL

To update an Access Control List (ACL) for a customer, send a PUT request to the ACL endpoint. Key Points:

The request updates only one ACL at a time for a given customer.
The customer associated with an existing ACL cannot be modified.
The okm_id field is optional:
a. If provided and the specified OKM exists, the ACL will be linked to the corresponding OKM.
b. If provided but the specified OKM does not exist, the update operation will fail, and an error will be returned.

PUT https://domain.name/api/v1/acls/{acl-id}?customer={customer}

Example request:

Authorization: {{JwtReadCreateAuthorization}}
Content-Type: application/json

{
  "id": "access_control_list_1", 
  "customer": "invu",
  "users": [
        {
            "user_id": 1,
            "pin_hash": "edc6f6aee2c323105cba0389d914f0a6b9e6980516df4fa31736fdc8ecac67a9",
            "auth_time": 4,
            "sounder": true,
            "sounder_delay": 10,
            "sounder_duration": 255,
            "sounder_volume": 0,    
            "permissions":[0,1]
        } ,
        {
            "user_id": 2,
            "pin_hash": "24fb82643120b8f385b528130fac187171ab6afca1b61710ae60cb036309f4a6",
            "auth_time": 8,
            "sounder": false,
            "sounder_delay": 10,
            "sounder_duration": 255,
            "sounder_volume": 0,
            "permissions":[1,0]
        }
    ],
    "locks": ["9998765432", "9998765433"],
    "user_data": {
      "label": "placehoder",
      "message": "placeholder"
    },
    "okm_id": "okm_1"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
"message": "Resource updated successfully",
"data": {
    "id": "access_control_list_1",
    "customer": "invu",
    "users": [
        {
            "user_id": 1,
            "pin_hash": "edc6f6aee2c323105cba0389d914f0a6b9e6980516df4fa31736fdc8ecac67a9",
            "auth_time": 4,
            "sounder": true,
            "sounder_delay": 10,
            "sounder_duration": 255,
            "sounder_volume": 0,    
            "permissions":[0,1]
        } ,
        {
            "user_id": 2,
            "pin_hash": "24fb82643120b8f385b528130fac187171ab6afca1b61710ae60cb036309f4a6",
            "auth_time": 8,
            "sounder": false,
            "sounder_delay": 10,
            "sounder_duration": 255,
            "sounder_volume": 0,
            "permissions":[1,0]
        }
        ],
        "locks": ["9998765432", "9998765433"],
        "user_data": {
            "label": "placehoder",
            "message": "placeholder"
        }
    }
}

Possible errors

Error Code	Description
400 Bad Request	Error: Error in updating access control list error: duplicate key value violates unique constraint “acl_id_customer_key”
403 Forbidden	{ "error_code": "UNAUTHORIZED_ACCESS", "error_msg": "Missing required scopes" }

DELETE

Sending a DELETE to the access-control-list endpoint will delete an access control list for the customer.

DELETE https://domain.name/api/v1/acls/{acl-id}?customer={customer}

Example request:

DELETE https://domain.name/api/v1/acls/access_control_list_1
Authorization: {{JwtReadDeleteAuthorization}}

Example response:

HTTP/1.1 204
No content

Possible errors

Error Code	Description
400 Bad Request	Error: Error in deleting access control list
403 Forbidden	{ "error_code": "UNAUTHORIZED_ACCESS", "error_msg": "Missing required scopes" }

PATCH

Not supported, the request will return

Error code	Description
405 Method Not Allowed	Cannot PATCH

Access Control List (ACL) API

Definition​

POST​

Create an Access Control List​

Possible errors​

GET​

Get all access lists for a customer​

Get ACLs for a customer, with pagination​

Get one specific ACL​

Possible errors​

PUT​

Update an ACL​

Possible errors​

DELETE​

Possible errors​

PATCH​

Definition

POST

Create an Access Control List

Possible errors

GET

Get all access lists for a customer

Get ACLs for a customer, with pagination

Get one specific ACL

Possible errors

PUT

Update an ACL

Possible errors

DELETE

Possible errors

PATCH