Create an API key with permissions

An API key lets a program call the Nodelets REST API and WebSocket. Each key holds a fixed list of permissions, and anything not on the list is refused.

Create the key

1. Sign in at https://dashboard.staging.nodelets.com and open Account.
2. Under API keys, choose Create key.
3. Enter a Key name that says where the key will be used, for example Greenhouse logger. Names are at most 100 characters.
4. Build the permission list. Each line has three choices, and Add permission adds another line.
5. Choose Create key, then copy the key from the next dialog. It starts with nlt_ and is shown once.

Send the key as a bearer token:

curl -H "Authorization: Bearer nlt_..." https://api.staging.nodelets.com/nodelets

Choose permissions

Each permission line names:

• a Nodelet, or All Nodelets
• a capability, meaning one property, action or event by name, or All capabilities
• an operation

Operation in the picker	Lets the key
Read value	Read a property’s current value from the device
Write value	Write a property
Watch live value	Receive a property’s live values on the WebSocket
Run action	Invoke an action
Receive event	Receive an event on the WebSocket
Read history	Read saved readings, the account feed and the collection health report
Read record	Read a Nodelet’s record of writes and actions
All operations	Every operation above

A new line starts as Read value on one Nodelet, so a key never starts with full access. When a line names one capability, the picker offers the operations its definition declares, plus Read history for a property. Read record applies to a whole Nodelet, so it needs All capabilities.

Some examples:

Purpose	Lines
A dashboard that shows one heater	Workshop heater · All capabilities · Read value, and Workshop heater · All capabilities · Watch live value
A script that sets one value	Workshop heater · setpoint · Write value
A logger that reads saved temperatures	All Nodelets · temperature · Read history
An auditor	All Nodelets · All capabilities · Read record

What a key sees

• A Nodelet the key does not name answers NOT_FOUND, the same as one that does not exist, and it is left out of the key’s listing.
• A capability the key is not given answers PERMISSION_DENIED (403), whether or not the device has a capability of that name.
• A key’s view of a Nodelet and its Thing Description shows only the capabilities and operations it was given.
• A refused attempt is counted on the Nodelet’s record, which its owner can see.

Read history on one property reaches that property alone. A history query that names no property needs Read history on all capabilities of that Nodelet.

All Nodelets includes Nodelets added after the key was made. A line that names a capability matches it by name, so a later definition that reuses the name changes what the line reaches.

Change a key

A key’s permissions cannot be changed. Create a new key with the list you want, move the program to it, and delete the old key.

Delete a key

Under API keys, choose the delete button beside the key and confirm. The key stops working, its open WebSocket connections close, and a command it sent that has not yet left the cloud is not sent. If the page shows an error, the deletion is still being completed. The cloud carries on until it has finished, so you do not need to try again.

Limits

• A permission list is at most 15,360 bytes of JSON, which is about 250 Nodelets named once with one operation each. The limit comes from the size of the WebSocket’s stored state.
• Keys made before permissions existed hold all Nodelets, all capabilities and all operations.

Creating and deleting keys appear on the Account record, under Account.