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:

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

Generated by aglio on 09 Jun 2018