REST API

Examples

You can see examples and test this API here: Swagger UI

Authentication

To test endpoints that need authentication generate an auth token calling /login. Then click the button on the received email to validate this token.

After that pass the token as Authorization header:

Authorization: TOKEN your-token-here

Errors

When API call returns an error you will get a response like this:

{
    "error": {
        "code": 1,
        "message": "Error description"
    }
}

When a call is successful you will get something like this:

{
    "result": {
       "someContent": "someValue"
    }
}

List or possible error codes:

-1: requesting action that needs authentication
-32602: invalid params
0: general error
1: the auth token has not been validated via email
2: don’t have permissions to access a resource
3: something was not found
4: cannot insert something because it already exists
5: integrity checks for firmware failed
6: when enabling a firmware update for a lock with version <= than current
7: when enabling a beta firmware for a lock that doesn’t allow betas
8: when integrity checks for an egg failed
9: when user tries to delete email that is set as contact email
10: when trying to add a time restriction with hour range where end <= start
11: when adding a time restriction with a weekday <0 or >6
12: when adding a time restriction with a monthday <1 or >31
13: when adding a time restriction with a month <0 or >11
14: when trying to create more key copies than allowed
15: when trying to set max_copies to a negative number
16: when user already has a key for that lock
17: when trying to create ACL and its max_copies + brothers.max_copies > father.max_copies
18: when creating an ACL with a permission that the parent doesn’t have
19: when ACL validity period falls completely outside of parent ACL validity period
20: when an email is already used by another user
21: when trying to pass lock ownership to a non-existing user
22: when trying to pass a wrong day to logs search
23: when trying to do something with a non-existing user
24: when trying to do something with a non-existing group
25: when trying to create an ACL passing both email & group id
26: when trying to create/modify a group with field max_members <= 0
27: when trying to add a group member exceeds max_members
28: when trying to use as replacement a lock that has more than 1 key or has 1 but it’s not the owner one
29: when trying to do some action with an actuator that doesn’t exist
30: when receiving string with XSS characters
31: when trying to delete an account while owning a lock
32: when trying to login with a non-existing email
33: when failed sending login email
34: when date range start if greater than end
35: when passing an invalid timezone
36: when creating a key exceeds hardware’s max_keys
37: when trying to assign keys to hardware but manufacturer doesn’t have enough available keys

API Reference

account

DELETE /account

Delete current user account

Delete current user account.

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /account/info

Get current user info

Get current user info

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.info.contact_email (string) – Contact email
result.info.has_groups (boolean) – True if user is owner or admin of some group
result.info.has_locks (boolean) – True if user is owner or admin of some lock
result.info.manufacturers[] (string) –
result.info.manufacturers_data[].id (string) –
result.info.manufacturers_data[].name (string) –
result.info.notifications_new_keys (boolean) – The user receives notifications on new keys
result.info.shoot_token (string) – Token used on /shoot

POST /account/info/push

Save push notification id

Save the Firebase messaging id so we can send push notifications to this device.

Parameters

lock_id (string) – Lock id

Request JSON Object

push_id (string) – Firebase messaging device id for push

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

emails

GET /account/emails

Get emails for user

Get list emails for current user.

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.emails[].email (string) – Email

POST /account/emails

Add email to user account

Add email to current user’s account. User will receive an email to validate it.

Request JSON Object

email (string) – Email to add (required)
lang (string) – Language used for validation email (e.g. en, es)
timezone (string) – Timezone used for validation email (e.g. Europe/Madrid)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

DELETE /account/emails/{email}

Delete email from account

Delete email from current user’s account.

Parameters

email (string) – Email to delete

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /account/emails/validation/{validationToken}

Validate adding email to user account

Validate adding email to user account. This is used on email sent when adding a new email.

Parameters

validationToken (string) – Validation token received via email when adding a new email

Query Parameters

lang (string) – Language locale (e.g. en, es)

Status Codes

200 OK – OK

POST /account/info/contact_email

Set user contact email

Set user contact email.

Request JSON Object

email (string) – Contact email

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

POST /account/info/notifications

Set user notifications settings

Set user notifications settings.

Request JSON Object

new_keys (boolean) – If true user receives notifications on new keys

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

auth

GET /account/sessions

Get active sessions

Get active sessions for current user.

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.sessions[].device_desc (string) – Session description
result.sessions[].device_id (string) – Session id
result.sessions[].last_use (integer) – When was last used (Unix time in secs)

DELETE /account/sessions/{device_id}

Delete session

Delete session so user cannot use its token to call API.

Parameters

device_id (string) – Session id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /account/validation/{validationToken}

Validate auth token

Validates an auth token got on /login. This is used on email sent when login in.

Parameters

validationToken (string) – Validation token received via email when login in

Query Parameters

lang (string) – Language locale (e.g. en, es)

Status Codes

200 OK – OK

GET /auth_ping

Ping with authentication

Ping that checks if the passed auth token is valid

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

POST /login

Login

Get an auth token to use with the API. Need to click link on received email to validate token

Request JSON Object

device_desc (string) – Readable description for this session (required)
device_id (string) – Unique random id that identifies this session (required)
email (string) – User’s email (required)
lang (string) – Language code (e.g.: en, es…)
public_key (string) – Public key of the device we are login in (so keys will be encrypted for him)
recatpcha (string) – Recaptcha Token (required)
timezone (string) – Timezone for this session (e.g.: Europe/Madrid…)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.token (string) – Token for authentication (read received email to activate)

GET /logout

Closes current session

Closes current session.

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

audits

GET /audits

Gets audit entries

Get audit entries

Query Parameters

manufacturer (string) – Manufacturer id
mac (string) – Returns audits for this device
type (string) – Returns audits with this type
from (string) – Return audits with creation date >= this Unix epoch (e.g. 1635499586)
to (string) – Return audits with creation date <= this Unix epoch (e.g. 1635499586)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.audits[].created (integer) – Creation Unix time
result.audits[].data (object) – Audit data
result.audits[].mac (string) – MAC
result.audits[].manufacturer (string) – Manufacturer
result.audits[].type (string) – Type
result.audits[].virkey_id (string) – Virkey Id

GET /manufacturers/{manufacturer_id}/config

Gets manufacturer config

Get manufacturer config

Parameters

manufacturer_id (string) – Manufacturer id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.config.available_keys (integer) – Number of keys the manufacturer has to assign to its hardware
result.config.show_available_keys (boolean) – If true show available keys on manufacturer page

boards

POST /board/default_actuators

Get default actuators for board

Get default actuators for board.

Request JSON Object

ca_key (string) – CA public key used by device (required)
egg (string) – Information from device (required)
public_key (string) – Public key on device (required)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.default_actuators[].name (string) – Actuator name
result.default_actuators[].time (integer) – If > 0: tenths of second it will keep connected on press. If -1 will act as a switch
result.max_actuators (integer) – Max. number of actuators configurable on this board

util

POST /eggs

Upload egg from device

Eggs contain information from the hardware device that needs to be updated on the cloud (logs, firmware update progress…).

Returns eggs for the device to do things like update its clock.

Request JSON Object

eggs[][] (integer) –

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.eggs[][] (integer) –
result.ok (boolean) – Success

GET /ping

Check server is online

Check server is online

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success
result.ts (integer) – Time on server

GET /shoot

Activate actuator remotely

Sends push notification to app and tries to “press” actuator. Useful for IFTTT integration.

Query Parameters

token (string) – Secret token (shown on app settings)
filter (string) – Text that identifies the actuator to be pressed. Will be searched on nearby locks & actuators

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /version

Get API version

Get version of the server

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.buildTime (string) – Date for this server build
result.commit (string) – Commit hash for this server build
result.version (string) – Version of the server

firmwares

POST /firmwares

Upload new firmware

Upload new firmware.

Request JSON Object

beta (boolean) – True if firmware is beta
firmware (string) – Firmware data (required)
signature (string) – Firmware signature (required)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /firmwares/{hash}

Get firmware

Get firmware

Parameters

hash (string) – Firmware hash

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.firmware (string) – Firmware data
result.hash (string) – Firmware hash

DELETE /locks/{lockID}/firmware_upgrade

Cancel firmware update

Cancel a previouly selected firmware upgrade.

Parameters

lock_id (string) – Lock id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

POST /locks/{lockID}/firmware_upgrade

Select firmware to update device

Select firmware the device will be updated to.

Parameters

lock_id (string) – Lock id

Request JSON Object

version (integer) – Version to upgrade to

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /locks/{lockID}/firmware_upgrades

Get available firmware upgrades for lock

Get available firmware upgrades for lock

Parameters

lock_id (string) – Lock id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.firmwares[].beta (boolean) – True if firmware is beta
result.firmwares[].version (integer) – Firmware version

groups

GET /groups

Get groups

Returns all groups this user owns or is admin of

Query Parameters

summary (boolean) – Returns summary result (less fields but faster)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.groups[].id (integer) – Group id
result.groups[].max_members (integer) – Maximum number of members
result.groups[].name (string) – Group name
result.groups[].owned (boolean) – True if group is owned by current user

POST /groups

Create group

Creates group of users

Request JSON Object

max_members (integer) – Maximum number of members (required)
name (string) – Group name (required)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.group_id (integer) – Id of created group
result.ok (boolean) – Success

DELETE /groups/{group_id}

Delete group

Deletes group of users

Parameters

group_id (string) – Group id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /groups/{group_id}

Get group

Gets data data from group of users

Parameters

group_id (string) – Group id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.group.id (integer) – Group id
result.group.max_members (integer) – Maximum number of members
result.group.name (string) – Group name
result.group.owned (boolean) – True if group is owned by current user

POST /groups/{group_id}

Modify group

Modifies group of users

Parameters

group_id (string) – Group id

Request JSON Object

max_members (integer) – Maximum number of members (required)
name (string) – Group name (required)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /groups/{group_id}/admins

Get group admins

Get group admins.

Parameters

group_id (string) – Group id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.admins[].email (string) – Admin email

POST /groups/{group_id}/admins

Add admin to group

Add admin to group (user must exist).

Parameters

group_id (string) – Group id

Request JSON Object

email (string) – New admin email (required)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

DELETE /groups/{group_id}/admins/{email}

Delete admin from group

Delete admin from group

Parameters

group_id (string) – Group id
email (string) – Admin email

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /groups/{group_id}/members

Get users from group

Get all users from group

Parameters

group_id (string) – Group id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.members[].email (string) – User email
result.members[].name (string) – User name

POST /groups/{group_id}/members

Add user to group

Add user to group

Parameters

group_id (string) – Group id

Request JSON Object

email (string) – User email (required)
lang (string) – Language for welcome email
name (string) – User name

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

DELETE /groups/{group_id}/members/{email}

Delete user from group

Delete user from group

Parameters

group_id (string) – Group id
email (string) – User email

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /groups/{group_id}/members/{email}

Get user from group

Get user from group

Parameters

group_id (string) – Group id
email (string) – User email

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.member.email (string) – User email
result.member.name (string) – User name

POST /groups/{group_id}/members/{email}

Modify user on group

Modify user on group

Parameters

group_id (string) – Group id
email (string) – User email

Request JSON Object

name (string) – User name

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

POST /groups/{groupID}/change_owner

Change group owner

Change group owner. Only the group owner can pass ownership to another user.

Parameters

group_id (string) – Group id

Request JSON Object

to (string) – Email of new group owner

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /members

Search group members

Search group members

Query Parameters

email (string) – Returns group members with this email

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.member.email (string) – User email
result.member.name (string) – User name

manufacturers

POST /hardware/{mac}/add_max_keys

Assign keys from manufacturer to hardware

Removes keys from manufacturer and adds them to hardware’s max keys

Parameters

mac (string) – Hardware MAC

Request JSON Object

email (string) – Email of the user that bought the keys
keys (integer) – Number of keys to add

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /manufacturers/{manufacturer_id}/hardware

Query hardware for manufacturer

Query hardware for manufacturer.

Parameters

manufacturer_id (string) – Manufacturer id

Query Parameters

format (string) – Format to return data: json or csv (json by default). When getting CSV it returns these fields: mac,lastVirkeyID,timezone,product,board,firmwareVersion,replacedWith,creationTime,activationTime,invoiceDate,invoiceUnixTime,actuatorsConfig,usedKeys,maxKeys
from_creation (number) – Return hardware with creation date >= this Unix epoch (e.g. 1635499586)
to_creation (number) – Return hardware with creation date <= this Unix epoch (e.g. 1635499586)
timezone (string) – Timezone used for dates generated on CSV (e.g. Europe/Madrid)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.hardware[].activation (integer) –
result.hardware[].actuators[].name (string) – Actuator name
result.hardware[].actuators[].time (integer) – If > 0: tenths of second it will keep connected on press. If -1 will act as a switch
result.hardware[].board (string) –
result.hardware[].creation (integer) –
result.hardware[].firm_version (integer) – Version of the firmware
result.hardware[].invoice (integer) –
result.hardware[].last_virkey_id (string) –
result.hardware[].mac (string) –
result.hardware[].max_keys (integer) –
result.hardware[].product (string) –
result.hardware[].replaced_with (string) –
result.hardware[].timezone (string) –
result.hardware[].used_keys (integer) –

keys

GET /keys

Get keys for current user

Get keys for current user with needed crypto data to activate actuators.

Query Parameters

last (string) – Get keys modified after last
no_crypto (string) – If true don’t return crypto data

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.keys[].actuator_names[] (string) –
result.keys[].ca_key (string) – CA public key
result.keys[].color_button_bg (string) – Background color for key button
result.keys[].color_button_text (string) – Text color for key button
result.keys[].created (integer) – Creation unix time
result.keys[].device_key (string) – Crypto payload readable by the lock
result.keys[].email (string) – User email
result.keys[].firm_version (integer) – Firmware version to update to
result.keys[].group_id (integer) – Group id
result.keys[].group_name (string) – Group name
result.keys[].hide_ads (boolean) – Don’t show ads
result.keys[].image (string) – Image to show near key
result.keys[].labels[].actuator (integer) – Number of actuator label will activate
result.keys[].labels[].id (string) – Label id
result.keys[].lock_name (string) – Lock name
result.keys[].manufacturer (string) – Id of the manufacturer of the lock
result.keys[].modified (integer) – When key was modified (used to ask for keys modified after this)
result.keys[].scan_hidden (boolean) – Hide in scan
result.keys[].user_key (string) – Crypto payload readable by the user device
result.keys[].virkey_id (string) – Lock id
result.ts (integer) – Server Unix time in millis

GET /locks/{lock_id}/acl

Get keys for lock

Get keys for lock

Parameters

lock_id (string) – Lock id

Query Parameters

summary (boolean) – Returns summary result (less fields but faster)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.acl[].access_logs (boolean) – Access logs registered for this key
result.acl[].delete_expired (boolean) – Autodelete when key out of validity
result.acl[].email (string) – User email
result.acl[].end (string) – End date of key validity (e.g. 2006-01-02T15:04:05)
result.acl[].group_id (integer) – Group id
result.acl[].name (string) – Name on the key
result.acl[].permissions[] (string) –
result.acl[].restrictions[].hours[].end (string) – Hour end (e.g. 03:30)
result.acl[].restrictions[].hours[].start (string) – Hour start (e.g. 02:00)
result.acl[].restrictions[].monthdays[] (integer) –
result.acl[].restrictions[].months[] (integer) –
result.acl[].restrictions[].type (string) – Type of restriction: allow/deny
result.acl[].restrictions[].weekdays[] (integer) –
result.acl[].start (string) – Start date of key validity (e.g. 2006-01-02T15:04:05)
result.acl[].trusted (boolean) – User for this key is trusted to set time on lock
result.acl[].user_id (integer) – User id
result.acl[].virkey_id (string) – Lock id

POST /locks/{lock_id}/acl

Create/modify key

Creates or modifies key. Can pass email or group_id to create key for user or for a group

Parameters

lock_id (string) – Lock id

Request JSON Object

access_logs (boolean) – Access logs registered for this key
delete_expired (boolean) – Autodelete when key out of validity
email (string) – User’s email (required if group_id is not passed)
end (string) – End date of key validity (e.g. 2006-01-02T15:04:05) (required)
group_id (integer) – Group id (required if email is not passed)
lang (string) – Language to use for welcome email sent to user
name (string) – Key name
permissions[] (string) – Email of new group owner
restrictions[].hours[].end (string) – Hour end (e.g. 03:30)
restrictions[].hours[].start (string) – Hour start (e.g. 02:00)
restrictions[].monthdays[] (integer) –
restrictions[].months[] (integer) –
restrictions[].type (string) – Type of restriction: allow/deny
restrictions[].weekdays[] (integer) –
start (string) – Start date of key validity (e.g. 2006-01-02T15:04:05) (required)
trusted (boolean) – User for this key is trusted to set time on lock

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) –

DELETE /locks/{lock_id}/acl/{emailOrGroupID}

Delete key

Deletes key for and email or group_id.

Parameters

lock_id (string) – Lock id
emailOrGroupID (string) – User email or group id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /locks/{lock_id}/acl/{emailOrGroupID}

Get key

Get key data

Parameters

lock_id (string) – Lock id
emailOrGroupID (string) – User email or group id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.aclEntry.access_logs (boolean) – Access logs registered for this key
result.aclEntry.delete_expired (boolean) – Autodelete when key out of validity
result.aclEntry.email (string) – User email
result.aclEntry.end (string) – End date of key validity (e.g. 2006-01-02T15:04:05)
result.aclEntry.group_id (integer) – Group id
result.aclEntry.name (string) – Name on the key
result.aclEntry.permissions[] (string) –
result.aclEntry.restrictions[].hours[].end (string) – Hour end (e.g. 03:30)
result.aclEntry.restrictions[].hours[].start (string) – Hour start (e.g. 02:00)
result.aclEntry.restrictions[].monthdays[] (integer) –
result.aclEntry.restrictions[].months[] (integer) –
result.aclEntry.restrictions[].type (string) – Type of restriction: allow/deny
result.aclEntry.restrictions[].weekdays[] (integer) –
result.aclEntry.start (string) – Start date of key validity (e.g. 2006-01-02T15:04:05)
result.aclEntry.trusted (boolean) – User for this key is trusted to set time on lock
result.aclEntry.user_id (integer) – User id
result.aclEntry.virkey_id (string) – Lock id

locks

GET /locks

Get locks

Get list of locks user owns or is admin of

Query Parameters

summary (boolean) – Returns summary result (less fields but faster)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.locks[].access_logs (boolean) – Record access logs
result.locks[].actuators[] (string) –
result.locks[].actuators_data[].name (string) – Actuator name
result.locks[].actuators_data[].time (integer) – If > 0: tenths of second it will keep connected on press. If -1 will act as a switch
result.locks[].administrable (boolean) – Logged user can admin this Lock
result.locks[].allow_beta (boolean) – Lock allows beta firmwares
result.locks[].auto_update (boolean) – Lock will update with last firmware automatically
result.locks[].board (string) – Board name
result.locks[].buy_keys_url (string) – URL for buying keys for this lock
result.locks[].can_buy_keys (boolean) – Can buy keys for this lock
result.locks[].color_button_bg (string) – Color of button background on scan
result.locks[].color_button_text (string) – Text color of button on scan
result.locks[].description (string) – Lock description
result.locks[].firm_version (integer) – Version of the firmware
result.locks[].hw_id (string) – BLE locks id (different on Android/iOS)
result.locks[].image_resized (string) – Hash of resized lock image
result.locks[].key_version (integer) – Current key version
result.locks[].mac (string) – Hardware mac
result.locks[].manufacturer (string) – Manufacturer id
result.locks[].max_keys (integer) – Maximum number of keys available
result.locks[].name (string) – Lock name
result.locks[].ota_version (integer) – Version of firmware selected for updating
result.locks[].owned (boolean) – Logged user owns this lock
result.locks[].product (string) – Product name
result.locks[].scan_hidden (boolean) – Don’t show on scan
result.locks[].timezone (string) – Timezone (e.g. Europe/Madrid)
result.locks[].ts (integer) – Unix time from last egg received from device
result.locks[].update_hash (string) – Hash of firmware being updated
result.locks[].update_offset (integer) – Progress of firmware being updated
result.locks[].update_size (integer) – Size of firmware being updated
result.locks[].update_start (boolean) – Firmware update in progress
result.locks[].update_version (integer) – Version of firmware being updated
result.locks[].used_keys (integer) – Number of keys used
result.locks[].virkey_id (string) – Lock id

POST /locks

Register new lock

Register new lock. Used by the mobile app to register a new Nearkey device.

Request JSON Object

actuators[] (any) –
allow_beta (boolean) – Allow beta firmwares
ca_key (string) – CA public key used by device (required)
create_key (boolean) – If true a key wil be created for current user (the owner)
description (string) – Lock description
egg (string) – Information from device (required)
hw_id (string) – BLE id of device (required)
name (string) – Lock name
public_key (string) – Public key on device (required)
timezone (string) – Timezone (e.g. Europe/Madrid)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.num_actuators (integer) – Number of actuators available on lock
result.ok (boolean) – Success

DELETE /locks/{lock_id}

Delete lock

Delete lock.

Parameters

lock_id (string) – Lock id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /locks/{lock_id}

Get lock

Get lock data.

Parameters

lock_id (string) – Lock id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.lock.access_logs (boolean) – Record access logs
result.lock.actuators[] (string) –
result.lock.actuators_data[].name (string) – Actuator name
result.lock.actuators_data[].time (integer) – If > 0: tenths of second it will keep connected on press. If -1 will act as a switch
result.lock.administrable (boolean) – Logged user can admin this Lock
result.lock.allow_beta (boolean) – Lock allows beta firmwares
result.lock.auto_update (boolean) – Lock will update with last firmware automatically
result.lock.board (string) – Board name
result.lock.buy_keys_url (string) – URL for buying keys for this lock
result.lock.can_buy_keys (boolean) – Can buy keys for this lock
result.lock.color_button_bg (string) – Color of button background on scan
result.lock.color_button_text (string) – Text color of button on scan
result.lock.description (string) – Lock description
result.lock.firm_version (integer) – Version of the firmware
result.lock.hw_id (string) – BLE locks id (different on Android/iOS)
result.lock.image_resized (string) – Hash of resized lock image
result.lock.key_version (integer) – Current key version
result.lock.mac (string) – Hardware mac
result.lock.manufacturer (string) – Manufacturer id
result.lock.max_keys (integer) – Maximum number of keys available
result.lock.name (string) – Lock name
result.lock.ota_version (integer) – Version of firmware selected for updating
result.lock.owned (boolean) – Logged user owns this lock
result.lock.product (string) – Product name
result.lock.scan_hidden (boolean) – Don’t show on scan
result.lock.timezone (string) – Timezone (e.g. Europe/Madrid)
result.lock.ts (integer) – Unix time from last egg received from device
result.lock.update_hash (string) – Hash of firmware being updated
result.lock.update_offset (integer) – Progress of firmware being updated
result.lock.update_size (integer) – Size of firmware being updated
result.lock.update_start (boolean) – Firmware update in progress
result.lock.update_version (integer) – Version of firmware being updated
result.lock.used_keys (integer) – Number of keys used
result.lock.virkey_id (string) – Lock id

POST /locks/{lock_id}

Modify lock

Modifies lock data.

Parameters

lock_id (string) – Lock id

Request JSON Object

access_logs (boolean) – Record access logs
actuators[] (object) –
auto_update (boolean) – Lock will update with last firmware automatically
description (string) – Lock description
name (string) – Lock name (required)
scan_hidden (boolean) – Don’t show on scan
timezone (string) – Timezone (e.g. Europe/Madrid) (required)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) –

POST /locks/{lock_id}/color

Set colors for lock’s buttons

Set colors for lock’s buttons.

Parameters

lock_id (string) – Lock id

Request JSON Object

button_bg (string) – Background color for lock’s buttons (e.g. #FFFFFF)
button_text (string) – Text color for lock’s buttons (e.g. #FFFFFF)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

DELETE /locks/{lock_id}/image

Remove current image from lock

Remove current image from lock

Parameters

lock_id (string) – Lock id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

POST /locks/{lock_id}/image

Set image for lock

Set image for lock. This image will be shown on app near the lock’s actuators.

Parameters

lock_id (string) – Lock id

Request JSON Object

image (string) – Image data (supports: GIF, PNG & JPEG) (required)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

GET /locks/{lock_id}/labels

Get labels for lock

Get labels for lock

Parameters

lock_id (string) – Lock id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.labels[].actuator (integer) – Number of actuator label will activate
result.labels[].id (string) – Label id

POST /locks/{lock_id}/labels

Add label to lock

Adds label to lock. They are used to associate QR and NFC tags to lock.

QR/NFC must contain a URL like https://api.nearkey.io/a/shot?label=some_label_id

Parameters

lock_id (string) – Lock id

Request JSON Object

actuator (integer) – Number of actuator the label will activate
id (string) – Label id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

DELETE /locks/{lock_id}/labels/{label_id}

Delete label from lock

Delete label from lock

Parameters

lock_id (string) – Lock id
label_id (string) – Label id to delete

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

POST /locks/{lockID}/change_owner

Change lock owner

Change lock owner. Only the lock owner can pass ownership to another user.

Parameters

lock_id (string) – Lock id

Request JSON Object

to (string) – Email of new lock owner

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

POST /locks/{lockID}/replace

Configure new hardware for an existing lock

Copies all settings and keys from lock_id to the lock passed on the request body. After that will delete lock_id.

Used when replacing hardware for a lock keeping its settings and keys.

Parameters

lock_id (string) – Id of lock to copy from

Request JSON Object

replacement (string) – Lock id to copy to

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

admins

GET /locks/{lock_id}/admins

Get admins for lock

Get admins for lock

Parameters

lock_id (string) – Lock id

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.admins[].email (string) – Admin email

POST /locks/{lock_id}/admins

Add admin for lock

Add admin for lock (user must exist).

Parameters

lock_id (string) – Lock id

Request JSON Object

email (string) – Hour end (e.g. 03:30)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

DELETE /locks/{lock_id}/admins/{email}

Delete admin from lock

Delete admin from lock

Parameters

lock_id (string) – Lock id
email (string) – Admin email to delete

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.ok (boolean) – Success

logs

GET /logs/{lock_id}

Get access logs for device

Get access logs for device

Logs can be returned as JSON or as a CSV (format param)

Parameters

lock_id (string) – Lock id

Query Parameters

day (string) – Get logs from a day: (e.g. 2018-01-30)
from (string) – Get logs from start day: (e.g. 2018-01-30)
to (string) – Get logs until end day: (e.g. 2018-01-30)
format (string) – Format of result: can be json or csv
lang (string) – Language for result (e.g. en, es)

Status Codes

200 OK – OK

Response JSON Object

error.code (integer) – Error code
error.data (object) – Error data
error.message (string) – Readable error description
result.logs[].boot_cnt (integer) – Boot counter
result.logs[].email (string) – User email
result.logs[].log_cnt (integer) – Log counter
result.logs[].name (string) – User name
result.logs[].opcode (integer) – Operation code
result.logs[].param (integer) – Operation param
result.logs[].repeat (integer) – Number of times this line is repeated (to eliminate adjacent entries that are equal)
result.logs[].result (integer) – Operation result
result.logs[].ts (string) – Timestamp of access
result.logs[].user_id (integer) – User id