Introduction

With the Nold Cloud API, you can sync guests with your database, manage guests, create and edit them. The Nold Cloud API is designed for developers, engineers, or anyone else who’s comfortable creating custom-coded solutions or integrating with RESTful APIs.

The Nold Cloud API is built on HTTP. Our API is RESTful and follows these points:

  • URL paths, URL query parameter names, and JSON field names are case sensitive.

  • The HTTP status indicates whether an operation failed or succeeded, with extra information included in the HTTP response body.

  • All APIs return standard error code formats.

  • Unexpected query parameters are NOT ignored.

  • Unexpected JSON fields in the request body are NOT ignored.

  • Uses built-in HTTP capabilities for passing parameters and authentication.

  • Always returns JSON.

API Key and Secret

If you want to set up an integration with your Nold Cloud account, you’ll need to generate an API key. You authenticate to the Nold Cloud API by providing your API key and Secret in the request. You can manage your API key in the ‘Profile’ tab of the Control Panel.

  1. Click your profile image to expand the options, and choose Ingegrations.

  2. Open the API section.

  3. Copy an existing API key or click the Create A Key button.

API keys grant full access to your account and should be protected the same way you would protect your password. In particular, there are a few common scenarios to keep in mind when working with API keys.

  • Give each integration its own API key, and assign labels to each key so you know which key goes with which application. If a specific API key is compromised, you can disable that key without disabling access to all of your other integrations.

  • Be careful not to expose the key to the public (such as in screenshots, videos, or help documentation). Remember that blurring your data isn’t always enough. It’s best to use “cut” functions in your graphics program to remove the data completely.

  • If a key needs to be shared, generate a new key and label it accordingly so it can be disabled, if needed. Never email the API key, because it would allow access to your Nold account if hackers were to compromise your email account.

Base URL

All API URLs referenced in this documentation start with the following base part and works through SSL only:

https://api.nold.io/public/

Date format

The api returns JSON for all API calls. Every returned date is using the ISO 8601, for example:

2016-07-02 13:18:42.697Z

Response format

The API returns JSON for every request in the following format:

{
  "status": "success, fail or error",
  "code": "error_code",
  "message": "Printable message.",
  "data": "{Object}"
}

We expose API errors in two ways: standard HTTP response codes and human-readable messages in JSON format. Here is a table of the HTTP response codes:

Code Description
200 Everything worked as expected
201 The requested resource is created
204 The requested resource is deleted
400 Bad Request - Often missing a required parameter
401 Unauthorized - No valid API key provided
403 Request Failed - Parameters were valid but request failed
404 Not Found - The requested item doesn’t exist
409 Duplicate - The requested resource already exists
500, 502, 503, 504 Server Errors - something is wrong on the server end

Authentication

There are 2 authentication methods for the API: HTTP Basic authentication and OAuth2. The easiest way to authenticate is using HTTP Basic authentication. Enter your API Key as your username and supply your API Secret as the password. Your HTTP client library should have built-in support for Basic authentication.

We recommend using the OAuth2 method for increased security. In this situation the developer does a one-time exchange of their API Keys for an Access Token. This Access Token is time limited and must be periodically refreshed. To request a token, you need to send a request to our API

POST /public/token HTTP/1.1
Host: api.nold.io
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <Base64UrlSafe(apiKeyId:apiKeySecret)>

grant_type=client_credentials

If the credentials are valid, you will get an Access Token response that looks like this:

{
  "access_token": "eyJ0eXAiOiJKV1QiL...",
  "token_type": "bearer",
  "expires_in": 3600
}

The response is a JSON object which contains:

  • access_token - Your OAuth Access Token. This can be used to authenticate on future requests.

  • token_type - This will always be “bearer”.

  • expires_in - This is the amount of seconds (as an integer) for which this token is valid.

With this token you can now make requests to your API. This request is simpler, as only thing you need to supply is Authorization header with the Access Token as a bearer token. If you are using curl, that request looks like this:

curl -v -H "Authorization: Bearer eyJ0eXAiOiJKV1QiL..." https://api.nold.io/public/devices

Devices

Use this endpoint to list all of your activated devices and relays. If you have a Nold Open device with both of the relays activated, the response will contains two separate results with the same ID, but the relay number and device name will be different. You need to use both the device ID and the relay number in your other requests.

List devices

GET https://api.nold.io/public/devices
Responses200404
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "code": "devices_found",
  "message": "Devices found an returned",
  "data": [
    {
      "_id": "576fe7d52f61fa02cf3a57c3",
      "sn": "XXXXXXXX",
      "time": "2016-06-26T14:33:57.514Z",
      "name": "First device relay 1",
      "relay": 1,
      "image": ""
    },
    {
      "_id": "576fe7d52f61fa02cf3a57c3",
      "sn": "XXXXXXXX",
      "time": "2016-06-26T14:33:57.514Z",
      "name": "First device relay 2",
      "relay": 2,
      "image": ""
    },
    {
      "_id": "577126e016a48b1de7f8a298",
      "sn": "XXXXXXXX",
      "time": "2016-06-27T13:15:12.505Z",
      "name": "Second device",
      "relay": 1,
      "image": ""
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "status": "fail",
  "code": "not_found",
  "message": "You don't have any devices."
}

List devices
GET/devices

List all of your devices. The response data contains the device informations, such us the name, device ID and image.


Invite

Use this endpoint to add guests to your system and share access with them for your devices and doors.

Invite guests

POST https://api.nold.io/public/invite
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "guests": [
    {
      "email": "test@nold.io",
      "name": "Test name"
    }
  ],
  "devices": [
    {
      "_id": "58236150c8a36d5044ee86cd",
      "relay": "1"
    },
    {
      "_id": "58236150c8a36d5044ee86cd",
      "relay": "2"
    }
  ],
  "key": {
    "type": "online"
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "code": "invite_processed",
  "message": "Invites processed.",
  "data": [
    {
      "guest": {
        "name": "Test name"
        "email": "test@nold.io",
        "_id": "5827963789af379b34e5afc0"
      },
      "device": {
        "_id": "5af82524ad02d34e9c750b6e",
        "relay": 1,
        "name": "Nold Open #1"
      },
      "key": "https://nold.test-app.link/Q1G0dxyYBN",
      "key_id": "5b1bf2cb39183325bc217965",
      "status": "success"
    }
  ]
}

Invite guests
POST/invite

Share keys with your guests using this endpoint. You can invite more than one user if the guests parameter is an array. The name field is optional but recommended. The response data will contain an array containing the data of the invited guest and informations about the invite(Was the invite was successful, if not, why not?) You can submit an existing guest ID instead of the email addres. If the email address already exists, the key will be generated to the existing guest.

Parameters:

  • guests - Required. An array containing the guest info:

    • _id - Use an existing Guest ID. In this casse, the email and the name field is ignored.
    • email - Required if Guest ID is not supplied. The guest’s email address.
    • name - Optional. The guest’s name
    • avatar - Optional. The guest’s photo(a link to an image)
    • phone - Optional. The guest’s phone number(international format)
  • devices - An array containing your device ID and relay number. If omitted, the guest will be added anyway to your contact list

    • _id - Use an existing Device ID
    • relay - Use an existing relay id, 1 or 2
  • key - An object to setup the virtual key details the guests will receive, like start and expiration date. See available options below.

You can setup custom restrictions. Currently four type exists. The details of the key needs to be added to the key parameter in the request.

Unlimited

Unlimited access, works until manually revoked. Simply set the type parameter to “unlimited”

{
  "key": {
    "type": "unlimited"
  }
}

Online

Unlimited access, but also features activity logging(this key only works online). Simply set the type parameter to “online”

{
  "key": {
    "type": "online"
  }
}

Range

Key with start and expiration date/time set, with activity logging(this key only works online). Set the type parameter to “range” and define the start and expiration dates

{
  "key": {
    "type": "range",
    "from": "2018-10-30T12:08:30+01:00",
    "to": "2018-11-10T12:08:30+01:00"
  }
}

Recurring

Key with start and expiration date/time set, that works only on specific days, with activity logging(this key only works online). Set the type parameter to recurring and define each day with a start and expiration time

{
  "key": {
    "type": "recurring",
    "from": "2018-10-30T12:08:30+01:00",
    "to": "2018-11-10T12:08:30+01:00",
    "days": [
      {
        "day": "2018-10-30T12:08:30+01:00",
        "start": "2018-10-30T12:08:30+01:00",
        "end": "2018-10-30T12:09:30+01:00"
      }
    ]
  }
}

You have one more optional parameter that works with every key type, called copies. By default, the key can be opened only once. With this, you can control how many phones can open the same key.

{
  "key": {
    "copies": 5
  }
}

Guest

Use this endpoint to manage guests. Get, edit or delete them.

Get guests

If you don’t specify a device, all of your guests will be returned. If you don’t specify a relay, it will be used #1 as a default value.

GET https://api.nold.io/public/guests/576fe7d52f61fa02cf3a57c3/1
Responses200404
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "code": "guests_found",
  "message": "Guests found.",
  "data": [
    {
      "email": "test@nold.io",
      "name": "Test name",
      "_id": "582393c8644c3a215ee2eac6",
      "time": "2016-11-09T21:23:20.432Z"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "status": "fail",
  "code": "no_guests",
  "message": "No guests invited for this device."
}

Get guests
GET/guests/{device_id}/{relay}

Get a list of guests for a specific device.

URI Parameters
HideShow
device_id
string (optional) Example: 576fe7d52f61fa02cf3a57c3
relay
string (optional) Example: 1

Manage Guest

POST https://api.nold.io/public/guest/576fe7d52f61fa02cf3a57c3
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "email": "test@nold.io",
  "name": "Test name",
  "avatar": "image.jpg"
}
Responses200400
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "code": "guest_updated",
  "message": "Selected guest is updated!",
  "data": {
    "email": "test@nold.io",
    "name": "Test name",
    "_id": "5827963789af379b34e5afc0",
    "keys": [
      {
        "device_id": "58236150c8a36d5044ee86cd",
        "relay": 1,
        "_id": "5828eaf131f8aff430ab7841",
        "restriction": {
          "mode": "none"
        },
        "loaded": false,
        "time": "2016-11-13T22:36:33.795Z",
        "type": "offline"
      }
    ],
    "time": "2016-11-12T22:22:47.148Z"
  }
}
Headers
Content-Type: application/json
Body
{
  "status": "fail",
  "code": "already_exists",
  "message": "Selected email is already invited.",
  "data": {
    "email": "test@nold.io",
    "name": "Test name",
    "_id": "5827963789af379b34e5afc0",
    "keys": [
      {
        "device_id": "58236150c8a36d5044ee86cd",
        "relay": 1,
        "_id": "5828eaf131f8aff430ab7841",
        "restriction": {
          "mode": "none"
        },
        "loaded": false,
        "time": "2016-11-13T22:36:33.795Z",
        "type": "offline"
      }
    ],
    "time": "2016-11-12T22:22:47.148Z"
  }
}

Edit guest
POST/guest/{guest_id}

Change the email address and the name. Optional note parameter exist for various use cases.

URI Parameters
HideShow
guest_id
string (required) Example: 576fe7d52f61fa02cf3a57c3

GET https://api.nold.io/public/guest/576fe7d52f61fa02cf3a57c3
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "code": "guest_returned",
  "message": "Selected guest found and returned.",
  "data": {
    "email": "test@nold.io",
    "name": "Test name",
    "_id": "5827963789af379b34e5afc0",
    "keys": [
      {
        "device_id": "58236150c8a36d5044ee86cd",
        "relay": 1,
        "_id": "5828eaf131f8aff430ab7841",
        "restriction": {
          "mode": "none"
        },
        "loaded": false,
        "time": "2016-11-13T22:36:33.795Z",
        "type": "offline"
      }
    ],
    "time": "2016-11-12T22:22:47.148Z"
  }
}

Get guest
GET/guest/{guest_id}

Get a single guest’s informations.

URI Parameters
HideShow
guest_id
string (required) Example: 576fe7d52f61fa02cf3a57c3

DELETE https://api.nold.io/public/guest/576fe7d52f61fa02cf3a57c3
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "code": "guest_updated",
  "message": "Selected guest is deleted!",
  "data": {
    "email": "test@nold.io",
    "name": "Test name",
    "_id": "5827963789af379b34e5afc0",
    "keys": [
      {
        "device_id": "58236150c8a36d5044ee86cd",
        "relay": 1,
        "_id": "5828eaf131f8aff430ab7841",
        "restriction": {
          "mode": "none"
        },
        "loaded": false,
        "time": "2016-11-13T22:36:33.795Z",
        "type": "offline"
      }
    ],
    "time": "2016-11-12T22:22:47.148Z"
  }
}

Delete guest
DELETE/guest/{guest_id}

Delete the selected guest. All existing keys will be revoked. If needed, the referred device status will be changed to pending.

URI Parameters
HideShow
guest_id
string (required) Example: 576fe7d52f61fa02cf3a57c3

Key

Use this endpoint to manage shared keys. Renew, edit or delete them.

Manage Keys

For each request, a guestID and a keyID needs to be supplied.

POST https://api.nold.io/public/key/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "guestID": "5815c967009d85974b7155ae",
  "keyID": "58176db9ae520eb480b48b53",
  "restriction": {
    "mode": "range",
    "start": "2016-10-30T12:08:30+01:00",
    "end": "2016-11-10T12:08:30+01:00"
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "code": "key_edited",
  "message": "Selected key is edited.",
}

Edit key
POST/key/

Change an existing shared key’s details(mainly the restrictions. See more info about this in the invite endpoint.)


PATCH https://api.nold.io/public/key/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
    "guestID": "5815c967009d85974b7155ae",
    "keyID": "58176db9ae520eb480b48b53",
}
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "code": "invited",
  "message": "Invited successfully.",
}

Renew key
PATCH/key/

This will send the invitation email again to the guest, so the link can be opened again.


DELETE https://api.nold.io/public/key/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
    "guestID": "5815c967009d85974b7155ae",
    "keyID": "58176db9ae520eb480b48b53",
}
Responses200404
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "code": "key_deleted",
  "message": "Selected key is deleted",
}
Headers
Content-Type: application/json
Body
{
  "status": "fail",
  "code": "not_valid_key",
  "message": "This key is invalid or doesnt exists."
}

Revoke key
DELETE/key/

Delete a key, aka revoke acces from a guest. If needed, PIN code will be changed on the device(only for offline keys).


Activity

Use this endpoint to get your activity feed. Multiple events are logged, each with a different code:

Code Description
sent Invitation sent to the guest
downloaded Guest downloaded / opened the invitation link
connected Guest connected to your device(only for online keys)
revoked Access revoked from a guest
refreshed Key refreshed by the guest(only for offline keys)
renewed Invitation link sent again to the guest
deleted Guest deleted
edited Guest edited
tried Guest tried to access your device, but failed(only for online keys)

Activity feed

Results are paginated. You can filter the results for a single device/relay and a guest. Everything is optional, if nothing set, all of your activity information is returned in a reveres chronology order.

GET https://api.nold.io/public/activity/?page=?limit=?devices=?guests=
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "code": "activity_feed_returned",
  "message": "Activity feed loaded.",
  "data": {
    "docs": [
      {
        "_id": "5828eaf231f8aff430ab7842",
        "time": "2016-11-13T22:36:34.952Z",
        "key": {
          "name": "Test device",
          "keyID": "5828eaf131f8aff430ab7841",
          "restriction": {
            "mode": "none",
          },
          "relay": 1,
          "deviceID": "58236150c8a36d5044ee86cd",
          "type": "offline"
        },
        "type": "sent",
        "guest": {
          "name": "Test name",
          "email": "test@nold.io",
          "guestID": "5827963789af379b34e5afc0"
        }
      }
    ],
    "total": 16,
    "limit": 1,
    "page": 1,
    "pages": 16
  }
}

Get activity feed
GET/activity/{?page}{?limit}{?devices}{?guests}

URI Parameters
HideShow
page
number (optional) Default: 1 

Page to return.

limit
number (optional) Default: 10 

The maximum number of results to return.

devices
array (optional) 

Filter results by an existing device or devices. For example: 58176db9ae520eb480b48b53|2 where 2 is the relay

guests
array (optional) 

Filter results by an existing guest or guests. For example: 5827963789af379b34e5afc0


Webhooks

Webhooks enable to call a script on your server when one or more events have happened on your activity feed. Kinda like event listeners or push notifications.

Configuration can be done through the Nold Cloud user interface. Simply login, click on your profile picture int he top right corner, select Integrations and toggle Webhooks. Available events:

Code Description
Device activation When you activate a new device
Guest invited When you invite a new guest
Guest accepted invite When the guest accepted your invite and started using your shared key
Guest used a key When a guest used one of your keys
Guest deleted When you deleted a guest

Verify

Each request will include a header called X-NOLD-SIGNATURE, which is generated using a secret key(generated and displayed when you create a webhook), along with the json encoded payload data sent in the request. To verify if the request came from Nold, compute the HMAC hash and compare it to the header value sent in the request. If the computed signatures match, you can be sure the request was sent from Nold. For example, with Javascript, you can verify the request like this:

var crypto = require('crypto');
var secret = 'YOURSECRET';
var body = req.body;
var signature = req.headers['X-NOLD-SIGNATURE'];
var hash = crypto.createHmac('sha1', secret).update(JSON.stringify(body)).digest('hex');
if(hash === signature) {
  console.log('valid');
} else {
  console.log('invalid');
}

Generated by aglio on 09 Jun 2018