NAV
curl

Introduction

Welcome to the Nabto Cloud API. The Nabto C─║oud API can be used to control one or more domains on the Nabto Cloud platform.

Get API version

curl "https://api.cloud.nabto.com/v1/version"
  -H "Authorization: Bearer apikey" 
{
  "version": "1.0.0",
}

HTTP Request

GET /v1/version

HTTP Response

A JSON representation of the API version.

Authentication

The Nabto Cloud API uses bearer token authentication. All request must include a Authorization header Authorization: Bearer apikey

curl -H "Authorization: Bearer apikey"

Domains

Get Domains

curl "https://api.cloud.nabto.com/v1/domains"
  -H "Authorization: Bearer apikey"
[
  "mydomain.example.net",
  "mydomain2.example.net"
]

Get a list of all domains available for this user.

HTTP Request

GET /v1/domains

HTTP Response

A JSON representation of all domains.

Create Domain

curl -XPOST "https://api.cloud.nabto.com/v1/domains" 
  -H "Authorization: Bearer apikey"
  -H "Content-Type: application/json"
  -d '{ "domain": "mydomain.example.net", "tags": {"foo": "bar"}, "allowSelfSigned": false }'

When a new device is added, its device ID will be: <ID>.<Domain> for this reason, domains should never start with a ..

Note: Depending on your contract, individual sub-domains may incur additional basestation license charges. Please confirm in your contract or contact Nabto support or your account manager for questions.

HTTP Request

POST /v1/domains

HTTP Response

A JSON representation of the newly created domain.

Get Domain

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net"
  -H "Authorization: Bearer apikey" 
{
  "domain": "mydomain.example.net",
  "created": "...",
  "tags": { "...": "..." }
}

HTTP Request

GET /v1/domains/:domain

HTTP Response

A JSON representation of the specified domain (currently no interesting information).

Modify domain

curl -XPOST "https://api.cloud.nabto.com/v1/domains/mydomain.example.net" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json" \
  -d '{"allowSelfSigned": true }'

returns the modified domain.

it’s deprecated to set allowSelfSigned here, instead use /keys.

Get Monthly Usage

Monthly usage is indexed from 1 meaning 2017 is represented as 2017 and january is represented as 1.

curl -XGET "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/usage/2016/07"
  -H "Authorization: Bearer apikey"
{
  "year": 2016,
  "month": 7,
  "count": 42,
  "relayBytes": 42
}

Retrieve how many devices was online on the given domain in the given month.

HTTP Request

GET /v1/domains/:domain/usage/:year/:month

HTTP Response

A JSON document describing the number of devices seen in a given month.

Get Devices

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/devices" \
  -H "Authorization: Bearer apikey"
{
  "devices": [
    {
      "domain": "mydomain.example.net",
      "deviceId": "zznjyy.mydomain.example.net",
      "region": "cn-north-1",
      "lastUpdate": "2016-10-18T10:17:24.299Z",
      "created": "2016-10-15T10:17:24.299Z"
    }
  ]
}

lastUpdate is the last time a device’s status was updated with the basestation. The status is updated when a device comes online and subsequently periodically batch updated (every 12 hours).

Get all the devices a basestation knows.

HTTP Request

GET /v1/domains/:domain/devices

HTTP Response

A JSON representation of the list of devices (currently not paginated).

Get Stats

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/stats" \
  -H "Authorization: Bearer apikey"
{
  "devicesConfigured": 42,
  "devicesSeenOnline": 38,
  "devicesSeenOnline24hr": 24
}

Get stats for a domain, stats are performance metrics which gives some idea about the usage of a given domain.

HTTP Request

GET /v1/domains/:domain/stats

HTTP Response

A JSON document with usage statistics.

Get Configured Or Seen Online Stats (alpha)

This query get exactly the number of devices which has been configured or seen online for a domain. The query is probably removed in the future.

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/stats-configured-or-seen-online" \
  -H "Authorization: Bearer apikey"
{
  "devicesConfiguredOrSeenOnline": 42
}

HTTP Request

GET /v1/domains/:domain/stats-configured-or-seen-online

HTTP Response

A JSON document with the number of devices seen online or configured for the given domain.

Domain keys

The keys resource control the keys for a given domain. There are two kind of keys, domain keys and device keys. Domain keys are used for controlling the default behavior for the domain where as the device keys are used to provide pr. device key configuration to override the default configuration for a given domain.

Get Domain Keys

curl -H "Authorization: Bearer apikey"
  https://api.cloud.nabto.com/v1/domains/mydomain.example.net/keys

The above command returns a JSON structured key description.

{
  "masterSecret": "",
  "preSharedKey": ""
}

HTTP Request

GET /v1/domains/:domain/keys

Modify Domain Keys

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/keys"
  -H "Authorization: Bearer apikey"
  -H "Content-Type: application/json"
  -d '{ "masterSecret":  "0102030405060708090a0b0c0d0e0f0102030405060708090a0b0c0d0e0f" }'

HTTP Request

POST v1/domains/:domain/keys

Post Parameters

Parameter Description
masterSecret domain master secret
preSharedKey domain pre shared key
firebaseServerKey firebase key used when sending firebase messages.
webhookUrl Webhook URL for push notifications.
webhookUser Webhook basic auth User name for push notifications.
webhookPass Webhook basic auth password for push notifications.
connectWebhookUrl Connect Webhook URL for connect validation.
connectWebhookUser Connect Webhook basic auth User name for connect validation.
connectWebhookPass Connect Webhook basic auth password for connect validation.
eventWebhookUrl Event Webhook URL for event notifications.
eventWebhookUser Event Webhook basic auth User name for event notifications.
eventWebhookPass Event Webhook basic auth password for event notifications.
allowSelfSigned Allow clients with self signed certificates to connect to devices.

Get All Device Keys

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/keys/devices" \
  -H "Authorization: Bearer apikey"

The above command returns json in the following format

{
  "keys": [
    { "deviceId": "...", "preSharedKey": "...", "tags": "...", "created": "..." },
    ...
  ]
}

HTTP Request

GET v1/domains/:domain/keys/devices

Bulk create device keys

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/keys/devices" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json" \
  -d '{ "count": 42, "tags": { "key": "value" } }'

The above command returns json in the following format:

{
    "count": 42,
    "batchId": 2,
    "keys": [
      {"deviceId": "...", "preSharedKey": "...", "tags": { "key": "value" } },
      ...
    ]
}

The bulk key create method generates a list of device ids and keys. The default alphabet id strings is “abcdefghijkmnopqrstuvwxyz3479” aka [a-z0-9] \ [0,1,2,5,6,8,l] see http://ux.stackexchange.com/questions/53341/are-there-any-letters-numbers-that-should-be-avoided-in-an-id

The default length for random ids is 8 it gives 29^8 500246412961 different possibilities.

The request object takes a count parameter and a tags parameter. Tags is of type map encoded in json.

The request returns a batch ID as a reference to all devices created with the specific call.

HTTP Request

POST v1/domains/:domain/keys/devices

Create device key batch with custom device IDs (Alpha)

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/keys/custom-devices" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json" \
  -d '{ "deviceIds": [dev1.mydomain.example.net, dev2.mydomain.example.net, ...], "tags": { "key": "value" } }'

The above command returns json in the following format:

{
    "batchId": 2,
    "keys": [
      {"deviceId": "...", "preSharedKey": "...", "tags": { "key": "value" } },
      ...
    ],
    "rejected": [
      "dev1.mydomain.example.net",
      ...
    ]
}

The create device key batch with custom device IDs method generates keys for a given list of device IDs.

The request object takes an array of device IDs and a tags parameter. Device IDs is an array of valid device IDs as strings and tags is of type map encoded in json.

The request returns a batch ID as a reference to all devices created with the specific call, an array of accepted device ID’s and their generated key, and and array of rejected device ID’s. Device ID’s will only be rejected if it already exists. If any device ID in the list is not a valid device ID, the entire list is rejected, and 400 is returned.

HTTP Request

POST v1/domains/:domain/keys/devices

Get Device Batch

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/keys/batch/5" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json"

The above command returns json in the following format: json-doc { "batchId": 5, "keys": [ {"deviceId": "...", "preSharedKey": "...", "tags": { "key": "value" } }, ... ] }

The get device batch method gets all devices created by a single invokation of bulk create device keys.

HTTP Request

GET v1/domains/:domain/keys/batch/:batchId

Get Device Key

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/keys/devices/a.mydomain.example.net" \
  -H "Authorization: Bearer apikey"

The above command returns json with the following format:

{
  "deviceId": "a.mydomain.example.net",
  "preSharedKey": "01010101010101010101010101010101"
}

HTTP Request

GET v1/domains/:domain/keys/devices/:deviceId

Generate a Device Key

curl -XPOST "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/keys/devices/a.mydomain.example.net" \
  -H "Authorization: Bearer apikey"

The above command returns json with the following format.

{
  "deviceId": "a.mydomain.example.net",
  "preSharedKey": "01010101010101010101010101010101"
}

set key for a device if it does not exists, return 409 if it exist

HTTP Request

POST v1/domains/:domain/keys/devices/:deviceId

Change a Device Key

curl -XPUT "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/keys/devices/a.mydomain.example.net" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json" \
  -d '{ "preSharedKey": "01010101010101010101010101010101" }'

The above command returns json with the following format.

{
  "deviceId": "a.mydomain.example.net",
  "preSharedKey": "01010101010101010101010101010101"
}

Updates an already existing device key

HTTP Request

PUT v1/domains/:domain/keys/devices/:deviceId

Query Parameters

preSharedKey

Devices

Get log for a device

This function returns the last logs for a device, the number of logs is limited by time and a maximum of 100.

curl -XGET "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/devices/:device/logs" \
  -H "Authorization: Bearer apikey"

Each returned event has a subset of the following fields.

[
  {
    "timestamp": "<iso8601>",
    "eventType": "<eventType>",
    "domain": "<domain>", // associated device domain
    "basestation": {
      "region": "<region>"
    },
    "device": {
      "id": "<id>",
      "ip": "<ip>", // public ip of the device
      "port": 0,    // public port
      "versionString": "<version>"
    },
    "client": {
      "id": "<id>",
      "ip": "<ip>", // public ip of the client
      "versionString": "<version>"
    },
    "connection": {
      "type": "P2P|RELAY|LOCAL",
      "receivedBytes": 0,
      "receivedPackets": 0,
      "sentBytes": 0,
      "sentPackets": 0,
      "duration": 0 // age of the connection in ms when this event was created.
    },
    "streamStats": { // stats for a stream when this event was created
      "rttAvg": 0, // average rtt in ms
      "receivedBytes": 0, 
      "receivedPackets": 0,
      "sentBytes": 0,
      "sentPackets": 0,
      "duration": 0,
      "status": "OPEN|CLOSED|CLOSED_ABORTED"
    }
  },
  ...
]

HTTP Request

GET /v1/domains/:domain/devices/:device/logs

HTTP Response

A JSON document with an array of events.

Get device attach information

Gets the current attach information for a device, the data returned is global device ip,port basestation ip,port and keepalive information for the specific device.

curl -XGET "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/devices/:device/attach-info" \
  -H "Authorization: Bearer apikey"
{
  "device": {
    "id": "<id>",
    "ip": "<ip>",
    "port": "<port>",
    "attachedTime": "ISO8601",
    "versionString": "<version",
    "encrypted": true|false,
    "state": "IDLE|AWAIT_ATTACH|ATTACHED",
    "version": {
      "custom": "" // custom version reported by the device.
    }
    "keepalive": {
      "seq": 0,
      "sent": 0,
      "received": 0,
      "lost": 0
    }
  }
}

HTTP Request

GET /v1/domains/:domain/devices/:device/attach-info

HTTP Response

If the device is currently attached, a json document is returned.

If the device is not known by the system, ie it has not been online for some time, a 404 is returned.

If the device is not attached to the basestation, which it is known to supposed to be attached to, a 404 is returned.

If the basestation instance where the device was last attached is not reachable or terminated, a 404 is returned.

Get device basestation tracelog state

This feature is used in development context where extra verbose log is required to understand why a device acts like it does. If tracelog is not enabled it returns 404.

curl -XGET "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/devices/:device/tracelog" \
  -H "Authorization: Bearer apikey"
{
  "ttl": 300
}

HTTP Request

GET /v1/domains/:domain/devices/:device/tracelog

HTTP Response

A JSON with start/end or 404 if no current tracelog is enabled for the device.

Enable/disable device basestation tracelog

Enables basestation tracelogging for a specific device.

curl -XPOST "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/devices/:device/tracelog" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json" \
  -d '{ "ttl": 300 }'
{
  "ttl": 300
}

HTTP Request

`POST /v1/domains/:domain/devices/:device/tracelog

param ttl, time to live in seconds from now.

HTTP Response

A JSON with start/end or error if it could not be set.

Gsp Certs

List Gsp Certs

Get a list of all gsp certs which the basestation knows. Each certificate is associated with a domain. The domain tells what devices a certificate matches. The certificate is choosen on a best match basis. Just like domain configurations.

curl "https://api.cloud.nabto.com/v1/gsp-certs" \
  -H "Authorization: Bearer apikey"

The above command returns json of the following format.

[
  { "domain": "xyz", "gspCert": "xyz", "tags": {}, "created": "iso8660" },
  ...
]

HTTP Request

GET /v1/gsp-certs

Create gsp cert

This request creates a gsp certificate if it does not already exists. If it does exists it is replaced with the new certificate. The certificate can be prepared as a json string with newlines with the following command: awk '$1=$1' ORS='\\n'

curl -XPUT "https://api.cloud.nabto.com/v1/gsp-certs/:domain" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json" \
  -d '{ "gspCert": "cert as pem string", "gspKey": "key as pem string", "tags": {"key", "value"}  }'

Alternatively prepare a cert.json file it makes the command simpler since the certificates can be tricky on the command line.

curl curl -XPUT "https://api.cloud.nabto.com/v1/gsp-certs/:domain" \ -H "Authorization: Bearer apikey" \ -H "Content-Type: application/json" \ -d @cert.json

The above command return the following json

{
  "domain": "xyz",
  "gspCert": "xyz",
  "tags": {},
  "created": "iso8660"
}

Update gsp cert

To update a gsp certificate, prepare the desired changes as a json string. Only gspCert, gspKey and tags can be updated. Returns 404 if the certificate does not exist.

curl -XPOST "https://api.cloud.nabto.com/v1/gsp-certs/:domain" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json" \
  -d '{ "gspCert": "cert as pem string", "gspKey": "key as pem string", "tags": {"key", "value"}  }'

HTTP Request

PUT /v1/gsp-certs/:domain

Delete gsp certificate

This deletes a gsp certificate and removes it from the basestations.

curl -XDELETE "https://api.cloud.nabto.com/v1/gsp-certs/:domain" \
  -H "Authorization: Bearer apikey"

Root Certs

List Root Certs

Get a list of all root certs which the basestation knows. Each certificate is associated with a certificate ID.

curl -XGET "https://api.cloud.nabto.com/v1/root-certs" \
  -H "Authorization: Bearer apikey"

The above command returns json of the following format.

[
  { "certId": "xyz", "rootCert": "xyz", "tags": {}, "created": "iso8660" },
  ...
]

HTTP Request

GET /v1/root-certs

Create root cert

This request creates a root certificate if it does not already exists. If it does exists it is replaced with the new certificate. The certificate can be prepared as a json string with newlines with the following command: awk '$1=$1' ORS='\\n'

curl -XPUT "https://api.cloud.nabto.com/v1/root-certs/:certId" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json" \
  -d '{ "rootCert": "cert as pem string", "tags": {"key", "value"}  }'

Alternatively prepare a cert.json file it makes the command simpler since the certificates can be tricky on the command line.

curl -XPUT "https://api.cloud.nabto.com/v1/root-certs/:certId" \ 
  -H "Authorization: Bearer apikey" \ -H "Content-Type: application/json" \
  -d @cert.json 

The above command return the following json

{
  "certId": "xyz",
  "rootCert": "xyz",
  "tags": {},
  "created": "iso8660"
}

Update root cert

To update a root certificate, prepare the desired changes as a json string. Only rootCert and tags can be updated. Returns 404 if the certificate does not exist.

curl -XPOST "https://api.cloud.nabto.com/v1/root-certs/:certId" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json" \
  -d '{ "rootCert": "cert as pem string", "tags": {"key", "value"}  }'

HTTP Request

PUT /v1/root-certs/:certId

Delete root certificate

This deletes a root certificate and removes it from the basestations.

curl -XDELETE "https://api.cloud.nabto.com/v1/root-certs/:certId" \
  -H "Authorization: Bearer apikey"

Users

The users endpoint is for creating and managing users and user access to the system.

Get All Users

curl -XGET "https://api.cloud.nabto.com/v1/users" \
  -H "Authorization: Bearer apikey"

The above command returns a JSON structured array og user ids like this:

[
  "admin1",
  "admin2"
]

Get User

Get a specific user

curl -XGET "https://api.cloud.nabto.com/v1/users/admin1" \
  -H "Authorization: Bearer apikey"

The above command returns a JSON structured object describing the user.

Create user

curl -XPOST "https://api.cloud.nabto.com/v1/users"

Modify user

curl -XPOST "https://api.cloud.nabto.com/v1/users/:userId"

Webhooks

Webhook URLs and optional credentials are configured with the Modify Domain Keys API request. The data posted to the different webhooks are described below.

Connect Webhooks

Connect webhooks are invoked when a client connects through the basestation, this gives to possibility for a third party to allow or reject connections. If the webhook returns something not status 200 OK or status 204 NO CONTENT the connect request is rejected.

HTTP Request

POST <webhook_url>

{
   "type": "client_connect_request",
   "device": {
       "id": "<device_id>"
   },
   "client": {
       "id": "<client_id>",
       "auth": {
           "key": "value"
           ...
       }
   }
}

HTTP Response

200 or 204 OK if the connect is allowed. All other responses leads to connect rejection.

Push Webhooks

Push webhooks are invoked when a uNabto device sends a push notification using the PNS ID UNABTO_PUSH_PNS_ID_WEBHOOK (enum value 2). If multiple notifications is available at the basestation at the same time, they may be sent in the same webhook invokation, as seperate entries in the messages array.

HTTP Request

POST <webhook_url>

{
    "messages" :
    [
        {
            "deviceId" : "xyz.cloud.nabto.net",
            "data" :
            {
                "custom" : "data",
                "foo" : "bar"
            }
        }
    ]
}

Event Webhooks

Event webhooks are invoked when certain events occur in the basestation. Currently device attach and device detach events are triggering the webhook with the eventType field set to GSP_ATTACH and GSP_DETACH, respectively. If multiple events have occurred, these may be delivered in a single webhook invocation.

Note that if a device restarts, the most recent event for the device after a few minutes is a detach event (even if the device is currently attached). This potentially confusing pattern occurs as the detach happens after a timeout interval, ie after the most recent attach event in case of restart.

For clarity, an attach id is then supplied in the webhook messages to be able to correlate attach and detach events: In the restart case, you will see two attach webhook invocations for the device with different attachId values. After the timeout period, a detach event follows with the first attachId value.

HTTP Request

POST <webhook_url>

{
        "events" :
        [
                {
                        "basestation" :
                        {
                                "region" : "eu-west-1"
                        },
                        "device" :
                        {
                                "id" : "j1qxsrxg.ug.cloud.dev.nabto.net",
                                "ip" : "90.183.131.131",
                                "port" : 52892,
                                "version" : "-"
                        },
                        "domain" : "ug.cloud.dev.nabto.net",
                        "attachId" : "83a32b07-bf2b-4559-9b38-aba8332b479c",
                        "eventType" : "GSP_ATTACH",
                        "timestamp" : "2018-03-06T06:23:09.270251Z"
                }
        ]
}

Errors

If a request succeeds no error object is returned. A succeeding request generally returns a 2xx status code. If there’s a problem with the way the client is making a request a 4xx error is generally thrown. If the problem is in the nabto-cloud-api a 5xx error is generally sent.

Error Codes

We are using http error codes when they make sense.

{
  "error": {
    "type": "<error_type>",
    "message": "<error_message>"
  }
}

Mock

Put Monthly Usage

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/usage/2016/10" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json" \
  -d '{ "count": 42 }'

The above gives a json document with the following structure.

{
  "year": 2016,
  "month": 7,
  "count": 42
}

Make it possible to inject fake monthly usage for a domain when testing against the mock api.

Post Devices

curl "https://api.cloud.nabto.com/v1/domains/mydomain.example.net/devices" \
  -H "Authorization: Bearer apikey" \
  -H "Content-Type: application/json"
  -d '{ "devices": [
    {
      "domain": "mydomain.example.net",
      "deviceId": "zznjyy.mydomain.example.net",
      "region": "cn-north-1",
      "lastUpdate": "2016-10-18T10:17:24.299Z"
    }
  ] }'

Make it possible to inject fake devices into the system.