Skip to content

kgorthi/noke-core-api-documentation

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

17 Commits
README.md
README.md
 
 

Repository files navigation

Nokē Core API Documentation

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.

Locks

POST /lock/

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

POST /unlock/

Used to unlock a lock. Requires a session string from the lock (see Nokē Mobile library documentation), 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)
tracking_key An optional string used to associate to lock activity 
{
    "mac": "XX:XX:XX:XX:XX:XX",
    "session": "0000040ba7b0d91f7f45ad25698a18375c7e4f16",
    "tracking_key": "[email protected]"
}

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

POST /unshackle/

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

POST /keys/

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).

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

POST /upload/

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), 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 mobile_api_key

BODY

{
    "logs": [
        {
            "session": "8675309j3nNy1V3G0ty0uRnUMB3r",
            "mac": "XX:XX:XX:XX:XX:XX",
            "received_time": 1518141482,
            "responses": ["8675f1v3tHr3309867", "530931gHTs1x75309"]
        }
	]
}

POST /activity/

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": [
        "[email protected]", 
        "[email protected]"
    ],    
    "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

POST /qc/

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

{
    "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

Firmware Update

Updating the firmware on a Noke device is a two-step process:

  1. Put the device into firmware update mode
  2. Send the firmware file to the device

Firmware Update Mode

To place a Noke device into firmware update mode, make a request to the fwupdate endpoint. This endpoint functions similarly to the unlock/ endpoint, but instead of unlocking the lock, returns a command that places the lock into firmware update mode.

POST /fwupdate/

Used to place a Noke device into firmware update mode. Requires a session string from the lock (see Nokē Mobile library documentation), and a mac address

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) 
{
    "mac": "XX:XX:XX:XX:XX:XX",
    "session": "8675309j3nNy1V3G0ty0uRnUMB3r",
}

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

Sending the Firmware file to the Noke Device

Once the Noke device is in firmware update mode, the firmware can now be updated by sending it a new firmware file. Noke devices use a chip provided by Nordic Semiconductor, therefore we've found that the best way to send a firmware file is to use the DFU library provided by Nordic.

Please follow the instructions provided by Nordic to implement their library into your mobile application. The DFU library is available for iOS and Android

Note: The firmware files needed are currently not available to the public. To get the firmware file needed to update a Noke device, please contact a member of the Noke development team.

About

Documentation for the Noke Core API

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published