Core API

Documentation

Lock

Unlock

Unshackle

Keys

Upload

Activity

Quick Clicks

DOCUMENTATION

Nokē Core Api

Overview

The Nokē Core API is a quick and simple way to integrate Nokē products with your existing software systems. This documentation covers the initial closed beta release.

Noke Mobile Library

Locks

Used to view information about locks. Supports finding a single lock, multiple locks, or all locks associated with a company.

Headers
Key Value
Content-Type application/json
Authorization Bearer api_key
Body
Parameter Description
macs An array of mac addresses from the lock(s)
Single Lock
    {
        "macs": [
            "XX:XX:XX:XX:XX"
        ]
    }                        
Multiple Locks
    { 
        "macs": [
            "XX:XX:XX:XX:XX", 
            "XX:XX:XX:XX:XY"
        ]
    }                       
All Locks
    { 
        //empty body
    }                   
Example Response
    {
        "result": "success",
        "message": "Command successfully completed",
        "error_code": 0,
        "data": {
            "locks": [
                {
                    "mac": "XX:XX:XX:XX:XX:XX",
                    "created_by": "J Doe",
                    "created_date": "2018-04-04T16:00:00Z",
                    "setup_count": 0,
                    "hw_version": "3p",
                    "fw_version": "2.10",
                    "serial": "XXX-XXX-XXXX",
                    "internal_battery": 0,
                    "external_battery": 0,
                    "status": "ready",
                    "flags": "none"
                }
            ]
        },
        "request": "lock"
    }                 
Parameter Description
result String value representing the result of the call. Either success or failure
message Readable description of the error
error_code Int value of the error thrown
locks Array of locks contain information about all the requested locks
mac Mac address of the lock
created_by Name of the user who registered the lock to the company
created_date Date that the lock was registered to the company
setup_count Number of times the lock has been set up. Used for tracking logs
hw_version Hardware version of the lock
fw_version Current firmware version of the lock
serial Serial number of the lock. This can also be found laser-etched onto the lock
internal_battery Value of the internal battery of the lock in millivolts
external_battery Value of the external battery of the lock in millivolts
status Status of the lock. Indicates if the lock is ready to be used or awaiting setup
flags An array of flags that indicate if any data needs to be synced to the lock (ie: quick-clicks, keys, etc). Syncing is handled automatically on the unlock endpoint
request Name of the request

Used to unlock a lock. Requires a session string from the lock (see Nokē Mobile library documentation: iOS/Android), a mac address, and can optionally take a tracking key to associate to lock activity.

Headers
Key Value
Content-Type application/json
Authorization Bearer api_key
Body
Parameter Description
mac The mac address of the lock
session Unique session generated by the lock and read by the phone when connecting. (see Nokē Mobile library documentation: iOS/Android)
tracking_key An optional string used to associate to lock activity
    {
        "mac": "XX:XX:XX:XX:XX:XX",
        "session": "0000040ba7b0d91f7f45ad25698a18375c7e4f16",
        "tracking_key": "bob@gmail.com"
    }                    
Example Response
    {
        "result": "success",
        "message": "Command successfully completed",
        "error_code": 0,
        "data": {
            "commands": "COMMAND_STRING_HERE"
        },
        "token": "TOKEN_HERE",
        "request": "unlock"
    }                    
Parameter Description
result String value representing the result of the call. Either success or failure
message Readable description of the error
error_code Int value of the error thrown
commands A string of commands sent to the lock by the Nokē Mobile library
request Name of the request

Used to remove the shackle from an HD padlock. Operates identically to the /unlock/ endpoint. Please see above for more details.

Used to request offline keys for a lock or locks, invalidate any existing keys, or view the status of any offline keys. These offline keys can be used by the mobile libraries to unlock the lock without an active network connection (see Nokē Mobile library documentation: iOS/Android).

Issue Keys

Headers
Key Value
Content-Type application/json
Authorization Bearer api_key
Body
Parameter Description
macs The mac address(es) of the lock(s)
tracking_keys Identifying string used to track activity and revoke keys
    {
        "issue": [
            {
                "macs": ["XX:XX","YY:YY","ZZ:ZZ"],
                "tracking_keys": ["bob","linda"]
            }
        ]
    }                    
Example Response
    {
        "data": {
            "locks": [
                {
                    "mac": "XX:XX",
                    "keys": [
                        {
                            "tracking_key": "bob",
                            "offline_key": "abc",
                            "unlock_command": "123"
                        },
                        {
                            "tracking_key": "linda",
                            "offline_key": "def",
                            "unlock_command": "456"
                        }
                    ]
                },
                {
                    "mac": "YY:YY",
                    "keys": [
                        {
                            "tracking_key": "bob",
                            "offline_key": "ghi",
                            "unlock_command": "789"
                        },
                        {
                            "tracking_key": "linda",
                            "offline_key": "jkl",
                            "unlock_command": "A00"
                        }
                    ]
                },
                    {
                    "mac": "ZZ:ZZ",
                    "keys": [
                        {
                            "tracking_key": "bob",
                            "offline_key": "ghi",
                            "unlock_command": "789"
                        },
                        {
                            "tracking_key": "linda",
                            "offline_key": "jkl",
                            "unlock_command": "A00"
                        }
                    ]
                }
            ]
        }
    }                    
Parameter Description
mac Mac address of the lock.
tracking_key String used to track activity associated with the key
offline_key Key used by the mobile library to encrypt the unlock command
unlock_command Command sent by the mobile library to the lock to unlock the lock
error_code Int value of the error thrown
request Name of the request
View All Issued Keys
Headers
Key Value
Content-Type application/json
Authorization Bearer api_key
Body
Parameter Description
macs The mac address(es) of the lock(s)
tracking_keys Identifying string used to track activity and revoke keys

Input (empty)

    {}                    

Input (limit by mac)

    {
        "display": {
            "macs": ["XX:XX"]
        }
    }                    

Input (limit by tracking key)

    {
        "display": {
            "tracking_keys": ["bob"]
        }
    }                    
Example Response
    {
        "data": {
            "locks": [
                {
                    "mac": "XX:XX",
                    "keys": [
                        {
                            "tracking_key": "bob",
                            "offline_key": "abc",
                            "unlock_command": "123"
                        },
                        {
                            "tracking_key": "linda",
                            "offline_key": "def",
                            "unlock_command": "456"
                        }
                    ]
                },
                {
                    "mac": "YY:YY",
                    "keys": [
                        {
                            "tracking_key": "bob",
                            "offline_key": "ghi",
                            "unlock_command": "789"
                        },
                        {
                            "tracking_key": "linda",
                            "offline_key": "jkl",
                            "unlock_command": "A00"
                        }
                    ]
                },
                    {
                    "mac": "ZZ:ZZ",
                    "keys": [
                        {
                            "tracking_key": "bob",
                            "offline_key": "ghi",
                            "unlock_command": "789"
                        },
                        {
                            "tracking_key": "linda",
                            "offline_key": "jkl",
                            "unlock_command": "A00"
                        }
                    ]
                }
            ]
        }
    }                 
Parameter Description
mac Mac address of the lock.
tracking_key String used to track activity associated with the key
offline_key Key used by the mobile library to encrypt the unlock command
unlock_command Command sent by the mobile library to the lock to unlock the lock
error_code Int value of the error thrown
request Name of the request
Revoke Keys
Headers
Key Value
Content-Type application/json
Authorization Bearer api_key
Body
Parameter Description
macs The mac address(es) of the lock(s)
tracking_keys Identifying string used to track activity and revoke keys

Input (revoke specific)

    {
        "revoke": [
            {"tracking_keys": ["bob"], "macs": ["XX:XX"]}
        ]
    }                   

Input (revoke all keys for mac/macs)

    {
        "revoke": [
            {
                "macs": ["YY:YY"]
            }
        ]
    }                   

Input (revoke all keys for tracking key/keys)

    {
        "revoke": [
            {
                "tracking_keys": ["bob"]
            }
        ]
    }                   
Example Response
    {
        "data": {
            "locks": [
                {
                    "mac": "XX:XX",
                    "keys": [
                        {
                            "tracking_key": "linda",
                            "offline_key": "def",
                            "unlock_command": "456"
                        }
                    ]
                },
                {
                    "mac": "YY:YY",
                    "keys": [
                        {
                            "tracking_key": "steve",
                            "offline_key": "jkl",
                            "unlock_command": "A00"
                        }
                    ]
                }
            ]
        }
    }                 
Parameter Description
mac Mac address of the lock.
tracking_key String used to track activity associated with the key
offline_key Key used by the mobile library to encrypt the unlock command
unlock_command Command sent by the mobile library to the lock to unlock the lock
error_code Int value of the error thrown
request Name of the request

Activity

Used to upload lock activity logs from a phone app using the Nokē Mobile library. Requires a session string from the lock (see Nokē Mobile library documentation: iOS/Android), a mac address, and can optionally take a tracking key to associate to lock activity.

NOTE: this route uses a mobile api key rather than the server api key.

Headers
Key Value
Content-Type application/json
Authorization Bearer api_key
Body
    {
        "logs": [
            {
                "session": "8675309j3nNy1V3G0ty0uRnUMB3r",
                "mac": "XX:XX:XX:XX:XX:XX",
                "received_time": 1518141482,
                "responses": ["8675f1v3tHr3309867", "530931gHTs1x75309"]
            }
        ]
    }                   

Used to view human-readable activity logs. Can find specific activity logs via filters or can be used to find the most recent activity for a company. Use as many or as few filters to narrow down specific activity data.

Headers
Key Value
Content-Type application/json
Authorization Bearer api_key
Body

All activity

    {
        //empty body
    }                  

Filtered

    {
        "lock_macs": [
            "XX:XX:XX:XX:XX:XX", 
            "XX:XX:XX:XX:XX:XY"
        ],
        "actions": [
            "unlock", 
            "alarm_triggered"
        ],
        "tracking_keys": [
            "bill@gmail.com", 
            "ted@gmail.com"
        ],    
        "before": "2018-05-23T20:08:34Z",
        "after": "2018-05-21T23:22:16Z"
    }                
Example Response
    {
        "result": "success",
        "message": "Command successfully completed",
        "error_code": 0,
        "data": {
            "activity": [
                {
                    "lock_mac": "XX:XX:XX:XX:XX:XX",
                    "action": "unlocked",
                    "recorded_time": "2018-03-15T17:26:41Z",
                    "range_date_start": "2018-03-15T17:20:43Z",
                    "range_date_end": "2018-03-15T17:20:43Z",
                    "tracking_key": ""
                },
                {
                    "lock_mac": "XX:XX:XX:XX:XX:XX",
                    "action": "locked",
                    "recorded_time": "2018-03-16T13:36:37Z",
                    "range_date_start": "2018-02-14T17:21:09Z",
                    "range_date_end": "2018-03-16T13:36:27Z",
                    "tracking_key": ""
                }
            ]
        },
        "request": "activity"
    }                
Parameter Description
result String value representing the result of the call. Either success or failure
message Readable description of the error
error_code Int value of the error thrown
activity Array of activity logs
lock_mac Mac address of the lock
action Action type of the log (ie: unlocked, locked)
recorded_time Date that the log was received by the mobile device
range_date_start If the exact time is not known (offline unlock or quick-click) this is the known earliest date the event could have occurred
range_date_end If the exact time is not known (offline unlock or quick-click) this is the known latest date the event could have occurred
tracking_key A string sent up on the unlock endpoint that can be used to associate activity
request Name of the request

Used to manage quick clicks for a lock or locks, revoke existing quick clicks, or view the status of any active quick clicks. Quick clicks can be used to unlock the lock without additional hardware.

Overview

A quick click is a code that allows entry to a lock via a series of long and short presses. This allows access to a lock without the use of additional software / hardware outside the lock once a quick click has been synced with a lock.

Quick click codes are represented as a string of 1's and 0's representing long and short presses respectively. The exact mechanism of how the quick click is used is dependent on the lock. For example, the standard padlocks use the shackle to enter quick clicks, while the HD padlocks and the U-Lock use a push button at the base of the lock. Typically, when entering a quick click, an LED on the lock will light up for a short press, and the LED will change color on a long press.

Quick clicks may be unlimited use, or may have a limited use count which is rendered unusable once the quick click is used a given number of times.

Quick clicks are created and removed via the API and are synced with a lock when an online unlock is requested.

Important:
  • • Each quick click MUST be a unique code. Quick click codes can only be reused once they have been removed from a lock.
  • • Quick clicks are only added to / removed from a lock via an online unlock.
  • • Each lock can hold up to 100 quick clicks.
  • • Quick click codes must be between 3 to 24 characters.
  • • Quick click's can have a limited use count between 1-244 uses OR may be unlimited use represented by a use count of 255.
Headers
Key Value
Content-Type application/json
Authorization Bearer api_key
Body

All activity

    {
        "issue": [
            {
                "mac": "XX:XX:XX:XX:XX",
                "quick_clicks":[
                    {	
                        "code": "101",
                        "uses": 255
                    },
                    {
                        "code": "010",
                        "uses": 10
                    }
                ]
            }
        ],
        "revoke": [
            {
                "mac": "XX:XX:XX:XX:XY",
                "quick_clicks":[
                    {	
                        "code": "101"
                    }
                ]
            }
        ],
        "display": {
            "macs": ["XX:XX:XX:XX:XX", "XX:XX:XX:XX:XY"]
        }
    }                 
Parameters
Key Description
issue An array of objects with a mac and at least one entry in quick_clicks. Used to create new quick clicks for a lock.
revoke An array of objects with a mac and at least one entry in quick_clicks. Used to remove existing quick clicks from a lock.
display Used to filter quick clicks included in the response. By default, no filter is applied.
quick_clicks An array of objects containing a code string and uses integer.
mac A single lock mac address.
macs An array of mac addresses that can be used as a display filter.
code A string consisting of 1's and 0's. The length of the string must be between 3-24 characters.
uses An integer between 1-255. Represents the total available uses of a quick_click. A value of 255 is an unlimited use quick click.
Example Response
    {
        "result": "success",
        "message": "Command successfully completed",
        "error_code": 0,
        "data":  [
            {
                "mac": "XX:XX:XX:XX:XX",
                "quick_clicks": [
                    {
                        "code": "101",
                        "pending": true,
                        "revoked": false,
                        "uses": 255
                    },
                    {
                        "code": "010",
                        "pending": true,
                        "revoked": false,
                        "uses": 10
                    }
                ]
            },
            {
                "mac": "XX:XX:XX:XX:XY",
                "quick_clicks": [
                    {
                        "code": "101",
                        "pending": false,
                        "revoked": true,
                        "uses": 255
                    }
                ]
            }
        ]
        "request": "qc"
    }               
Parameter Description
result String value representing the result of the call. Either success or failure
message Readable description of the error
error_code Int value of the error thrown
data Array of quick click states
mac Mac address of the lock
quick_clicks Array of quick clicks belonging to a specific lock
code The code used to unlock the given lock
uses The total number of uses for a quick click code
pending A Boolean flag; when true the given quick click will be added to the lock in the next online unlock
revoked A Boolean flag; when true the given quick click will be removed from the lock in the next online unlock
request Name of the request
Additional Questions?

If you need help or have any questions, please consider contacting support.