Cambrionix connect
Developers
Start here

Authentication

Service accounts, client credentials, token audiences and scopes for the Cloud API.

Every Cloud API request carries an OAuth 2.0 bearer access token. Server-to-server access uses the client credentials grant with a service account in your organisation.

Service accounts

Create a service account in Connect under Integrations → Create custom integration. Its Service ID is the client ID, and the groups you choose grant its permissions. Its tokens can only do what those groups allow, in the organisation it belongs to.

Client secrets are shown once, when they are created. You can create a new secret from the integration's page in Connect at any time, for example to rotate it, and delete the old one when nothing uses it any more.

Requesting a token

Request tokens from your organisation's token endpoint:

POST https://connect.cambrionix.com/api/v1/organizations/{organizationId}/oauth2/token

Send a JSON body:

FieldValue
grant_typeclient_credentials
client_idThe service account's client ID
client_secretThe service account's client secret
audienceThe audience of the API the token is for (see below)
scope* for every scope the service account is allowed, or a narrower list
curl -X POST "https://connect.cambrionix.com/api/v1/organizations/$CONNECT_ORGANIZATION_ID/oauth2/token" \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "client_credentials", "client_id": "'"$CONNECT_CLIENT_ID"'", "client_secret": "'"$CONNECT_CLIENT_SECRET"'", "audience": "b2d57903-6cc0-4099-aeaa-926d441a4128", "scope": "*"}'

The response is JSON with access_token, token_type (bearer), expires_in in seconds, and the scope the token was granted. Request a new token before the current one expires.

Audiences

A token is valid for one API. Use a separate token for each API you call, with that API's audience:

APIAudience
Authentication APIb65fa8fc-f2e3-4340-aa20-f12c66d2c980
Hardware APIb2d57903-6cc0-4099-aeaa-926d441a4128
Communications APIb2d57903-6cc0-4099-aeaa-926d441a4129
Locations APIb2d57903-6cc0-4099-aeaa-926d441a4130
Settings APIb2d57903-6cc0-4099-aeaa-926d441a4131
Downloads APIb2d57903-6cc0-4099-aeaa-926d441a4132

Each API's reference page also shows its audience, with a ready-made token request.

Sending the token

Send the access token in the Authorization header of every request:

curl https://connect.cambrionix.com/api/hardware/v1/hubs \
  -H "Authorization: Bearer $CONNECT_ACCESS_TOKEN"

Checking permissions

Each operation in the API reference lists the permission its token needs. To see what a token can do, send it to Get Effective Permissions with a token for the Authentication API's audience. The response names the service account or user the token was issued to, and lists every permission it can use in the organisation. A token requested with a narrower scope lists only that scope.

curl https://connect.cambrionix.com/api/v1/organization/effective-permissions \
  -H "Authorization: Bearer $CONNECT_ACCESS_TOKEN"

Errors

StatusMeaning
401The token is missing, has expired, or is for a different API's audience.
403The service account's groups do not allow the action, or the client exceeded a rate limit.