M2M Authorization

Sometimes a machine or application needs to talk to UpBlue directly, without a person logging in: a custom script that pushes measurements, an ERP that reads production counts, an external system that delivers data. This machine-to-machine (M2M) access works with service users and tokens.

💡

For collecting machine data, you rarely need this. The Collector, Cloud Connections and UpBlue Connect handle their own authorization. M2M tokens are for your own custom integrations.

How it works

The token you create in UpBlue is a client ID and client secret, not something you send to the API directly. Your integration trades them for a short-lived access token, and sends that access token with every API call:

Client ID + client secret (created once in UpBlue, stored safely) → identify the service user. The client ID is the service user’s email address.
Access token (requested at https://api.upblue.io/v1/token, valid for a limited time) → sent as Authorization: Bearer ... to the API.

⚠️

Sending the client secret directly as Bearer does not work: the API answers 403 invalid token. Always request an access token first (step 4).

Step by step

Create a service user

Create a service user on the tenant User management page. Use a name that tells what the integration is, for example [email protected]. The address is only an identifier.

Give it access

Open the organisation, go to its Users page and add the service user. Give it only what the integration needs:

Viewer to read data (tags, dashboards, operations).
Editor to change things through the API (connections, rules, alert rules).
User can insert to write data.

What each role can do. Without access to an organisation, every call for that organisation answers 403 no access.

Create a token

Go to the Token page (menu top right, tenant admins only).

Click on: and select the service user.

You get a Client ID (the service user’s email address) and a Client secret. The client secret is displayed once. Store it somewhere safe, such as a password vault or the secret store of your integration. A service user has one token; to get a new one, delete the old token first.

Request an access token

Send the client ID and client secret as form fields to the token endpoint, with grant type client_credentials:

curl (Linux / macOS)


CLIENT_ID='[email protected]'
CLIENT_SECRET='<the client secret from the Token page>'
 
ACCESS_TOKEN=$(curl -s https://api.upblue.io/v1/token \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  | jq -r .access_token)

The full answer of the token endpoint looks like this:


{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 43199
}

expires_in is the lifetime in seconds. There is no refresh token: when the access token is about to expire, request a new one in the same way. Reuse an access token until then, instead of requesting one for every call.

Find your tenant and organisation

Most endpoints have the tenant and organisation in the URL: /v1/{tenant_uuid}/organisation/{organisation_uuid}/.... Ask the API who the service user is and where it has access:


curl -s https://api.upblue.io/v1/current_user/info \
  -H "Authorization: Bearer $ACCESS_TOKEN"

returns the service user with its tenant_uuid, and


curl -s https://api.upblue.io/v1/current_user/organisation \
  -H "Authorization: Bearer $ACCESS_TOKEN"

lists the organisations it was added to in step 2, each with its organisation_uuid and role.

Call the API

Now any endpoint can be called with the access token. For example, list the tags of an organisation (needs Viewer):


curl -s "https://api.upblue.io/v1/$TENANT_UUID/organisation/$ORGANISATION_UUID/tag" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

All endpoints, their parameters, the role they need and example answers are in the API Reference.

Advice: one service user and token per integration. If a token is compromised, delete it: only that one integration needs a new token.

To revoke access, delete the token. Access tokens that were already issued stay valid until they expire.

Inserting data

With an access token, data can be pushed to the insert API. The service user needs User can insert in the organisation. Data is sent in the Influx line protocol format: the tag name, labels, a value and a timestamp per line — the same building blocks as everywhere in UpBlue.


POST https://stream.upblue.io/v1/{organisation_uuid}/iflp
Authorization: Bearer <access token>
Content-Type: text/plain

temperature,Site=Factory1,Area=Hall1 value=21.2 1757500000000000000

A successful insert returns HTTP 204. The inserted data appears as normal tags, ready for dashboards and alerts.

💡

Just want an external system to deliver data, without building anything? A Webhook connection is simpler: UpBlue gives you a URL, the system posts to it.

Troubleshooting

Answer	Cause
403 invalid token	The client secret was sent as `Bearer` instead of an access token, or the access token has expired.
403 no access	The service user is not in this organisation, or its role is too low for this endpoint. The API Reference shows the roles per endpoint.
Error from /v1/token	The client ID or client secret is wrong, was copied incompletely, or the token has been deleted. Create a new token.