Create an API key

An API key gives your own software access to the ModbusCloud REST API. The key belongs to the organisation and not to one customer. Your software therefore reads the gateways of all your customers, within the permissions of the key. What the API and webhooks deliver is described in REST API and webhooks.

What you need

• The role Owner or Admin in your organisation. For the other roles, API keys is not under Settings. Who may do what is described in Team members and roles.
• A safe place for the key, such as the settings of the software that uses it or a password manager.

Choose permissions

A key may only do what its permissions allow. If your software asks for something without the right permission, the API answers with status 403 and the code insufficient_scope.

The table shows the permissions that the endpoints in the API reference ask for. In the list of keys, each permission appears as a scope.

Select only what your software uses. With only these read permissions, a key changes nothing in your organisation. You do not need the other permissions in the window for the endpoints in the API reference.

You cannot change permissions afterwards. If your software needs another permission, create a new key and revoke the old one. If you want to receive alerts immediately instead of requesting them again and again, follow Set up a webhook.

Create a key

Create a separate key for each integration. Then you can revoke one without affecting the other integrations. Each key also has its own limit of 100 requests per minute.

1. Open the settings

   Go to Settings > API keys.

2. Open the window

   Click New key at the top right.

3. Enter a name

   In Name, enter a name that tells you which integration it is for, for example Office energy reporting.

4. Select permissions

   Under Permissions, select the permissions the integration needs. Create only works with a name and at least one permission.

5. Create the key

   Click Create. The window shows the key with the message Copy this key now. You won't be able to retrieve it later.

6. Copy the key

   Click the icon with the two squares to the right of the key. The portal shows Copied.

7. Store the key

   Paste the key into the software that uses it, or into a password manager.

8. Close the window

   Click Close. The key now appears in the list with the status Active.

The key consists of mlk_ followed by 64 characters. ModbusCloud only stores a hash of the key and its first 12 characters. These 12 characters appear under Prefix in the list. If you lose the key, create a new one and revoke the old one.

Test a key

The Test connection block shows whether a key works and what it may do. It is on the same page, below the list of keys.

1. Paste the key

   Paste the key into the field under Test connection.

2. Test the connection

   Click Test. If the key is correct, the block is now called API Explorer. It shows Key validated with the name, the organisation and the permissions of the key.

3. Open a category

   In the API Explorer block, click a category, for example Registers.

4. Try an endpoint

   For an endpoint with GET, click Try this endpoint. The portal sends the request with the key to the API and shows the response below.

If the key is unknown, revoked or not copied completely, the portal shows Connection failed with the HTTP status, for example HTTP 401. Categories the key has no permission for appear under Not available with this key. If an endpoint shows No gateway available, the key lacks Read gateways or your organisation does not have a gateway yet.

Outside the portal, you test the key with the /introspect endpoint. It returns the name, the permissions and the organisation of the key, and works with every valid key.

curl https://api.modbuscloud.com/v1/introspect \
  -H "Authorization: Bearer mlk_..."

In the demo account you cannot create keys. Try the API there with the public sandbox key from the quickstart of the API reference.

Allow writing registers

The permission Write registers is grey with the addition on request as long as control is not on for any gateway in your organisation. You request control per gateway, as described in Control registers from the portal.

If control is on for at least one gateway, you select Write registers for a new key. Writing through the API only works on the gateways where control is on. On any other gateway, the API answers with status 403 and the code write_not_enabled, whatever permissions the key has.

Revoke a key

A revoked key stops working immediately. The next request with that key gets status 401 with the code api_key_revoked.

Under Last used you see the date of the last request made with a key, even if that was a test in the portal. This shows you which keys are still in use. For a key that never made a request, it says Never.

1. Open the settings

   Go to Settings > API keys.

2. Find the key

   Find the key in the list by Name, or by the first characters under Prefix.

3. Revoke the key

   Click the red bin icon on the right of the row. The portal shows API key revoked and the status changes to Revoked.