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/tokenSend a JSON body:
| Field | Value |
|---|---|
grant_type | client_credentials |
client_id | The service account's client ID |
client_secret | The service account's client secret |
audience | The 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:
| API | Audience |
|---|---|
| Authentication API | b65fa8fc-f2e3-4340-aa20-f12c66d2c980 |
| Hardware API | b2d57903-6cc0-4099-aeaa-926d441a4128 |
| Communications API | b2d57903-6cc0-4099-aeaa-926d441a4129 |
| Locations API | b2d57903-6cc0-4099-aeaa-926d441a4130 |
| Settings API | b2d57903-6cc0-4099-aeaa-926d441a4131 |
| Downloads API | b2d57903-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
| Status | Meaning |
|---|---|
401 | The token is missing, has expired, or is for a different API's audience. |
403 | The service account's groups do not allow the action, or the client exceeded a rate limit. |