Web Console - API Documentation. console.kas.com.au

Web Console - API Documentation. console.kas.com.au

API DOCUMENTATION for console.kas.com.au


NEO CLOUD SMART LOCK

NEO CLOUD ACCESS CONTROL


Change Log

28/3/2021
  1. Update response to include status codes for when requests timeout.
  2. Added information about static api key.
  3. Add RFID commands
10/12/2019
  1. Added “GET LOCK AUDIT TRIAL” endpoint
  2. Updated details for passwords endpoints
4/8/2019
  1. Added “GET PASSWORDS” endpoint
  2. Retrieve API Key through an endpoint for added security
5/4/2019
  1. API is live
  2. Contact support@kas.com.au today to get your API key

Getting Started

Preface / Workflow : 

Our API is used to securely allow control of KAS devices from 3rd party applications and devices.  Our API does differ from others in certain ways.  Please take note of the following during any integration to ensure trouble free operation of KAS devices via this API.  

  1. Each API call will return a response indicating if the request has been processed correctly by our system. It is imperative you monitor each call individually to ensure success of the request.  
  2. Do not send an API call and assume it has been processed successfully just because the request has been sent. 
  3. API call limits are 30 API calls in the queue maximum.  If you attempt to push more than 30 calls at one time, they will be dropped by our server without error. 
  4. When setting a new RFID or pincode, you are required to send a "password_ID" / "rfid_id" along with the pincode/RFID number.  Please ensure you manage available  "password_ID" / "rfid_id" (code positions) as part of your integration.  You must avoid overwriting existing pincodes including those which are assigned to manually entered pincodes through our console interface. In order to avoid overwriting manually entered pincodes, we recommend using the "Get Online Passcodes" /  "Get Remote RFIDs" endpoints to ascertain which IDs are currently in use. Alternatively, as a quick/dirty solution, starting at password_ID/rfid_id position 120 will generally avoid overwriting manually entered pincodes/rifds.  


API Do's and Dont's

Do monitor our responses for errors and if so, display the error to your user for them to identify and rectify the problem.
Do monitor password_id/rfid_id's using the "Get Online Passcodes" /  "Get Remote RFIDs" endpoints to avoid overwriting codes.
Where possible use the dynamic API key and refresh it regularly to improve security.
To improve reliability, consider setting the clock using the Set Clock endpoint prior to sending a new pincode or RFID.  

Do not flood our server with unnecessary API calls (ie daily refresh of all codes for example).
Do not automatically retry codes "just to be certain".  Codes that have not been added successfully will return an error. Present the error to the user to allow your user to rectify the error and give your user the ability to retry failed commands manually. 

Step 1: Setup the lock using KAS Cloud App

In order to start using the API, each lock and gateway needs to be set up and bound to an account created on the KAS Cloud App. To do this, download the app and set up the lock. Note you can only conduct API calls on locks that are bound to your account.

KAS Cloud App Register
  1. https://support.kas.com.au/portal/en-gb/kb/articles/KAS_Cloud_Register
 Once the locks(s) and gateway(s) are activated to your account. Now retrieve your API Key.

Step 2: Retrieve your API Key

The API Key is used to authenticate your account with the locks and gateways that you own. It’s a way to identifying that you are in fact the owner of the device.

Example

API Key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI1YzI3Yjk3ZDRiMTJhMTAw

MTc3MTVlZmYiLCJsYXRlc3RfdG9rZW5fZGF0ZSI6IjIwMTktMDEtMTNUMDY6NTI6MzUuMjg5WiIsImlhdCI6MTU0NzUwMTM5Mn0.v8cuLVqum_sWuM1OsSWiM3MUpRYRHuSMsBYucZIYVk0


Notice:
The above string is an invalid token. Just for demo purposes only.

Get your API Key by consuming a HTTP endpoint. Note only Paid plans can use an API Key. Open API is only for paid plan users. Once you’ve signed up, request your API KEY from the endpoint you can start using the API.
Visit this page on details to obtain the API Key: https://console.kas.com.au/account/apikey
You can obtain a static api key here: https://console.kas.com.au/account/staic-api-key
The above link is protected and requires an account to view it. Create an account using the iOS or Android app, activate your lock/gateway, return to this link and all details are provided.

Notice:
  1. The API key is dynamic and needs to be refreshed every 24 hours.

Step 3: Start using the API

Now, your locks are setup using the KAS Cloud App and you have your API Key, proceed below to get started.

Overview and Specifications:
  1. To use the API, it requires a paid subscription.
  2. Use the HTTP Status code to check for call result.
  3. Unless specified please use HEADER : Content-type: Application/JSON
  4. Unless specified please use HEADER: x-auth-token: <Your API Key here>
Example
Content-type: Application/JSON
x-auth-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI1YzI3Yjk3ZDRiMTJhMTAw
MTc3MTVlZmYiLCJsYXRlc3RfdG9rZW5fZGF0ZSI6IjIwMTktMDEtMTNUMDY6NTI6MzUuMjg5WiIsImlhdCI6MTU0NzUwMTM5Mn0.v8cuLVqum_sWuM1OsSWiM3MUpRYRHuSMsBYucZIYVk0



API Commands

Remote Unlock

Unlocks the door.
Lock Gateway required to conduct this command. This command will work if a Gateway is 1) activated, 2) connected to a network, 3) within the specified range of the target door lock.
Tip: This API is perfect for IFTTT

Request

Request URL

https://cloud.kas.com.au/api/lockCommand/remoteUnlock/{factory_name}/{API_KEY}

factory_name is obtained from app interface. It either starts with ‘SS’ or ‘UL’. Replace API_KEY with your API Key retrieved from above.

Request Method

GET


Header

Content-type

application/json

Body

nil


Example:

GET https://cloud.kas.com.au/api/lockCommand/remoteUnlock/SS000510/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI1YzI3Yjk3ZDRiMTJhMTAwMTc3MTVlZmYiLCJsYXRlc3RfdG9rZW5fZGF0ZSI6IjIwMTktMDEtMTNUMDY6NTI6MzUuMjg5WiIsImlhdCI6MTU0NzUwMTM5Mn0.v8cuLVqum_sWuM1OsSWiM3MUpRYRHuSMsBYucZIYVk

Response

HTTP Status Code

Response Body (Plain Text)

200

{
“ack”:1
“message”: “Success”
}
or
{
“ack”:8
“message”: “Failed. Gateway offline or lock out of range.”
}
or
…

400

You are not the admin.
Invalid Token.
Lock is not found.

500

Unknown Error
   504
{
"ack": 504,
"message": "Gateway timeout. You should retry the request again now.",
ref: "UOWS-Xmuj"
}

Notice:
  1. This command may take up to 15 seconds to return a result. It’s because the command needs to be delivered through the gateway network and the lock will respond with the “ack” result.
  2. If you receive a 504 status code, it is because the gateway has timed out. Due to network, we can't guarantee if the request was delivered or not to the lock. If this scenario, you should retry the request immediately.

Add Online Password

Creates an 4-6 digit pin code for door access
You DO need a gateway connected to conduct this command.

Request

Request Header

x-auth-token

<your API Key here>

Request URL

https://cloud.kas.com.au/api/lockCommand/remotePassword/{factory_name}

factory_name is obtained from app interface. It either starts with ‘SS’ or ‘UL’.

Request Method

POST


Header

Content-type

application/json

Body

password_id: [Int] 101->200 ,
password_start_time: [String] YYMMDDHHmm,
password_end_time: [String] YYMMDDHHmm,
password: [String] 1234 or 223344 (4-6 digits),
password_name: [String] “John”,
email_checked: [Bool] – will send an email with the pincode, start time and end time detials to the email specified in “password_email”,
password_email: [String] – email format only,
password_message: [String] – custom message to be displayed in the email.

{
“password_id”:101,
“password_start_time”:”1901011200″,
“password_end_time”:”1904251200″,
“password”:”1234″,
“password_name”: “John”,
“email_checked”: false,
“password_email”: “test@email.com”,
“password_message”: “Watch out for the dog.”
}

Example

POST https://cloud.kas.com.au/api/lockCommand/remotePassword/S000510

Response

HTTP Status Code

Response Body (Plain Text)

200

{
“ack”: 1,
“message”: “Success”,
“password”: “1234”,
“l_factory_name”: “SS000910”,
“l_passwords”: [
{
“_id”: “5ca4249ea77c8200170e9ad8”,
“password_start_time”: “1904031142”,
“password_end_time”: “1909261142”,
“password_id”: 101,
“password_name”: “John Pin Code”,
“password”: “654321”,
“password_email”: “test@email.com”,
“password_message”: “From BH Web Console”
},
{
“_id”: “5ca6f3a0343edc7c9a028b80”,
“password_start_time”: “1901011200”,
“password_end_time”: “1904251200”,
“password_id”: 103,
“password_name”: “Cleaner pin”,
“password”: “0953”,
“password_email”: “test@test.com”,
“password_message”: “Go to front door.”
}
]
}

400

You are not the admin.
Invalid Token.
Lock is not found.
Password is already existing.
Error with Start and End times

500 / 504

Unknown Error
or

{
"ack": 504,
"message": "Gateway timeout. You should retry the request again now."
}

Notice:
  1. The response object will return the list of pincodes in the lock and their respective ID.
  2. The lock must have the clock set (Use the mobile app or Web Console to set it)
  3. If you Add Password with an ID which is already existing inside the lock memory, the API will override the ID with the new request.

Delete Online Password

Deletes an existing pin code in the lock memory
You DO need a gateway connected to conduct this command.

Request

Request Header

x-auth-token

<your API Key here>

Request URL

https://cloud.kas.com.au/api/lockCommand/remotePassword/{factory_name}

factory_name is obtained from app interface. It either starts with ‘SS’ or ‘UL’.

Request Method

DELETE


Header

Content-type

application/json

Body

password: [String] 1234 or 223344 (4-6 digits)
or
password_id: [Number] 101

{ “password”:”1234″
}
or
{
“password_id”:101
}

Example

DELETE https://cloud.kas.com.au/api/lockCommand/remotePassword/S000510

Response

HTTP Status Code

Response Body

200

{
“ack”: 1,
“message”: “Password deleted successfully.”
}
or
{
“ack”:8
“message”: “Failed. Gateway offline or lock out of range.”
}
or
…

400

You are not the admin.
Invalid Token.
Lock is not found.

500 / 504

Unknown Error
or

{
"ack": 504,
"message": "Gateway timeout. You should retry the request again now."
}

Notice:
  1. The response object will provide the appropriate “ack” if the password was deleted or not.
  2. If “ack” is not equal to 1, you should conduct the command again.
  3. There might be cases when HTTP status 200 is returned but the “ack” does not equal to 1. This means that your request is authenticated and you have the privilege to conduct the command, however, due to other circumstances, the requests fail.
  4. If you have trouble with this command, please delete it by the ID only and not the password value. There might be a case where duplicate password values are uploaded. Or please upload a new pin code over the ID and remove it afterward.

Get Online Passwords

Retrieves a list of existing pin code in the lock memory
You DO NOT need a gateway connected to conduct this command.

Request

Request Header

x-auth-token

<your API Key here>

Request URL

https://cloud.kas.com.au/api/lockCommand/remotePassword/{factory_name}

factory_name is obtained from app interface. It either starts with ‘SS’ or ‘UL’.

Request Method

GET


Header

Content-type

application/json

Body

none

none

Example

GET https://cloud.kas.com.au/api/lockCommand/remotePassword/S000510

Response

HTTP Status Code

Response Body

200

{
“l_factory_name”: “SS000761”,
“l_passwords”: [
{
“password_start_time”: “1907141412”,
“password_end_time”: “1907260000”,
“password_id”: 150,
“password_name”: “Cleaner 5213”,
“password”: “224126”
}
],
“l_lock_title”: “0101”
}

400

You are not the admin.
You are not the manager.
Invalid Token.
Lock is not found.

500 / 504

Unknown Error

Notice:
  1. This command is useful when need to see what pincodes are in the lock memory.

Get Lock Audit Trial

Retrieves a list of unlocking events from the server.
You DO NOT need a gateway connected to conduct this command.
Events will only be tracked in this list when a gateway is connected and nearby the lock. If a gateway is not online, some unlocking events may be missed.

Request

Request Header

x-auth-token

<your API Key here>

Request URL

https://cloud.kas.com.au/api/events/{factory_name}

factory_name is obtained from app interface. It either starts with ‘SS’ or ‘UL’.

Request Method

GET


Header

Content-type

application/json

Body

application

none

Example

GET https://cloud.kas.com.au/api/events/SS000510


Response

HTTP Status Code
 Response Body
200
 {
“events”: {
“_id”: “5ccf7997c89f1a0017350b78”,
“l_factory_name”: “SS001479”,
“events”: [
{
“date_added”: “2019-08-07T13:45:48.140Z”,
“_id”: “5d4ad60ccd2f7a0017ba7f1d”,
“event_type”: 1,
“event_type_label”: “Unlock Event”,
“battery”: 97,
“user_id”: 102,
“user_type”: 3,
“user_type_desc”: “password”,
“user_id_value”: “4321”,
“user_name”: “User 2”,
“date_added_timezone_name”: “Australia/Brisbane”
},
{
“date_added”: “2019-08-16T00:25:25.346Z”,
“_id”: “5d55f7f51d7b40001772b613”,
“event_type”: 1,
“event_type_label”: “Unlock Event”,
“battery”: null,
“user_id”: null,
“user_type”: 7,
“user_type_desc”: “Remote Unlock”,
“user_id_value”: “test@test.com”,
“user_name”: “User 1”,
“date_added_timezone_name”: “Australia/Brisbane”
}
],
“__v”: 0,
“l_lock_title”: “Door Lock 2”
},
“ack”: 0
}
40x
 You are not the admin.
You are not the manager.
Invalid Token.
Lock is not found.
500
 Unknown Error

Notice:

  • This command is useful when need to see an audit event.
  • Note: this will only show events that have been captured by the Gateway. If the Gateway if offline for a period of time, unlocking events may be missed and not shown in this list.
  • This list will show the last 3 months of unlocking events.
  • “ack”: 0 means you don’t need to validate the ack because this request receives server data and does not go directly to the lock.

Get Remote RFIDs

Retrieves a list of existing RFID Tags in the lock memory
You DO need a gateway connected to conduct this command.

Request

Request Header

x-auth-token

<your API Key here>

Request URL

https://cloud.kas.com.au/api/lockCommand/remoteRFID/{factory_name}

factory_name is obtained from app interface. It either starts with ‘SS’ or ‘UL’.

Request Method

GET


Header

Content-type

application/json

Body

none

none

Example

GET https://cloud.kas.com.au/api/lockCommand/remoteRFID/S000510

Response

HTTP Status Code

Response Body

200

{
“l_factory_name”: “SS000761”,
“l_rfids”: [{ ... }],
“l_lock_title”: “0101”
}

400

You are not the admin.
You are not the manager.
Invalid Token.
Lock is not found.

500 / 504

Unknown Error

Notice:
  1. This command is useful when need to see what RFID tags are in the lock memory.

Add Remote RFID


Adds a RFID to the lock.
You DO need a gateway connected to conduct this command.

Request

Request Header

x-auth-token

<your API Key here>

Request URL

https://cloud.kas.com.au/api/lockCommand/remoteRFID/{factory_name}

factory_name is obtained from app interface. It either starts with ‘SS’ or ‘UL’.

Request Method

POST


Header

Content-type

application/json

Body

rfid_id: [Int] 101->200 ,  or 101-> 2000 for Access Control Reader
rfid_start_time: [String] YYMMDDHHmm,

rfid_end_time: [String] YYMMDDHHmm,
rfid_name: [String] “John”,
uid: [String] - hexadecimal number of the rfid tag (4 hex bytes i.e 8 char string)
kas_uid: [String] - Number on the keycards provided by kas (10 digits only)
is_kas_uid: [Bool] - provide true if you are using kas_uid (ones provided by kas with 10 digits) - default False

{
“rfid_id”:101,
“rfid_start_time”:”1901011200″,

“rfid_end_time”:”1904251200″,

“rfid_name”: “John”,

"uid": "ABCD1234",
"kas_uid": "1234567890",
"is_kas_uid":true

}

Example

POST https://cloud.kas.com.au/api/lockCommand/remoteRFID/S000510

Response

HTTP Status Code

Response Body (Plain Text)

200

{
“ack”: 1,
“message”: “Success”,
“password”: “1234”,
“l_factory_name”: “SS000910”,
...
}

400

You are not the admin.
Invalid Token.
Lock is not found.
Password is already existing.
Error with Start and End times

500 / 504

Unknown Error
or

{
"ack": 504,
"message": "Gateway timeout. You should retry the request again now."
}

Notice:
  1. The response object will return the list of rfids in the lock and their respective ID.
  2. The lock must have the clock set (Use the mobile app or Web Console to set it)
  3. If you Add RFID with an ID which is already existing inside the lock memory, the API will override the ID with the new request.

Delete Remote RFID

Deletes an existing RFID in the lock memory
You DO need a gateway connected to conduct this command.

Request

Request Header

x-auth-token

<your API Key here>

Request URL

https://cloud.kas.com.au/api/lockCommand/remoteRFID/{factory_name}

factory_name is obtained from app interface. It either starts with ‘SS’ or ‘UL’.

Request Method

DELETE


Header

Content-type

application/json

Body

rfid_id: [Number] 101

{
“rfid_id”:101
}

Example

DELETE https://cloud.kas.com.au/api/lockCommand/remoteRFID/S000510

Response

HTTP Status Code

Response Body

200

{
“ack”: 1,
“message”: “RFID deleted successfully.”
}
or
{
“ack”:8
“message”: “Failed. Gateway offline or lock out of range.”
}
or
…

400

You are not the admin.
Invalid Token.
Lock is not found.

500 / 504

Unknown Error
or

{
"ack": 504,
"message": "Gateway timeout. You should retry the request again now."
}

Notice:
  1. The response object will provide the appropriate “ack” if the password was deleted or not.
  2. If “ack” is not equal to 1, you should conduct the command again.
  3. There might be cases when HTTP status 200 is returned but the “ack” does not equal to 1. This means that your request is authenticated and you have the privilege to conduct the command, however, due to other circumstances, the requests fail.
  4. If you have trouble with this command, please delete it by the ID only and not the password value. There might be a case where duplicate password values are uploaded. Or please upload a new pin code over the ID and remove it afterward.



Set Clock

Set the system time of the lock according to timezone settings in console.

Request

Request Header

x-auth-token

<your API Key here>

Request URL

https://cloud.kas.com.au/api/lockCommand/setClock/{factory_name}

factory_name is obtained from app interface. It either starts with ‘SS’ or ‘UL’.

Request Method

PUT


Header

Content-type

application/json

Example

PUT https://cloud.kas.com.au/api/lockCommand/setClock/S000510

Response

HTTP Status Code

Response Body

200

{
“ack”: 1,
“message”: “Clock set successfully.”
}
or
{
“ack”:8
“message”: “Failed. Gateway offline or lock out of range.”
}
or
…

400

You are not the admin.
Invalid Token.
Lock is not found.

500 / 504

Unknown Error
or

{
"ack": 504,
"message": "Gateway timeout. You should retry the request again now."
}

Notice:
  1. If “ack” is not equal to 1, you should conduct the command again.
  2. There might be cases when HTTP status 200 is returned but the “ack” does not equal to 1. This means that your request is authenticated and you have the privilege to conduct the command, however, due to other circumstances, the requests fail.


ACK and Response Values

Additionally to the HTTP response format. There might be a circumstance where you receive HTTP Status 200 but the request did fail. This is due to the gateway to lock connection. It could be bad network exception, gateway offline, bad lock signal or others. However, in the scenario that HTTP Status 200, we know that the request did reach the lock.
If this case, it is best to attempt the request again and set yours a number of tries. If the number of tries > 3 you can be certain there is an uncontrollable external factor failing the request. Here, you can handle the result accordingly.

If you receive HTTP Status 504, this is a gateway timeout. Due to networking or other factors, the request might have reached the lock but the gateway did not respond back fast enough before the request was closed. In this scenario, we can't guarantee if the request failed or succeed. You should retry the request again straight away if you receive HTTP Status 504.

Response:

Status: 200
Body:{ "ack": [Number], "message": [String], ... }
ACK
 Response Body (message)
 Correction
1
 Success
 n/a
2 / 4 / 6
 Error. Internal interface error. Failed. Timeout.
 Try command again
or
Invalid parameters. Try adding a pincode on top of the existing ID and delete that one later.
5
 Pending
 Waiting for the API response.
8
 Failed. No gateway nearby
 Ensure gateway is nearby. You might have to wait a few minutes for the gateway and lock to automatically discover each other.

Other ack responses which you may see:
1 Succeed to execute
2 Failed to execute
3 Instruction not pushed yet
4 Failed to push instruction
5 Instruction already pushed
6 Instruction already timeout
7 Instruction still in queue
8 No gateway for installation
10 instruction pending



    • Related Articles

    • KAS Cloud Web Console - User Guide

      Setup and Configuration To access the KAS Cloud Web Console you need to have the app and set up the hardware. (Skip if completed) Click here if you have not done this already Using the KAS Cloud Web console requires gateways Login Page Click on the ...

    • Changing KAS Web Console Gen 1 primary account

      In order to transfer all your locks to a different KAS web console email account please email the following information to support@kas.com.au with a subject line Migration of the Locks. 1) Username and Password of the current primary Account, from ...

    • KAS Cloud Web Console - Error "Something went wrong. Code: 400-Invalid token"

      This message is a validation error. Solution If you are receiving this error message, please try the following. Force close the app. Reopen the app. If the message still appears please try restarting your phone. Open the app. If the message still ...

    • KAS Cloud App Hardware Setup

      Setting up your Neo Cloud Lock/NEO ACR (Access Control Reader) DO NOT SET UP THE DEVICE UNTIL YOU HAVE INITIALISED THE LOCK TO CLOUD MODE Once you have power to the device, it will broadcast the SS number. The lock is in initialisation mode. You will ...

    • KAS Cloud App - Account Registration

      KAS Cloud App - Account Registration (Mobile App) Hardware Installation Account Registration (via Mobile App) and Hardware Activation is required before KAS Cloud Web Console is accessible. Download and Install the KAS cloud App using QR code below. ...