Skip to main content

Client Credentials Token Exchange Guide

Overview​

This guide explains how to create a Connect service, assign it the correct DFU permission, and use its client credentials to request a hub-scoped access token.

The token can then be used by an external service or application to perform DFU operations on a specific Cambrionix hub via the Hub API.

Prerequisites​

Before you begin, ensure you have:

  • Access to the relevant Cambrionix Connect organisation
  • Permission to create roles, groups, and services
  • The target hub serial number
  • The target host computer registered in Connect
  • The Hub API running on the target host computer

Step 1: Create a DFU Role​

Create a role that grants the service permission to perform DFU actions.

  1. In Connect, open the relevant organisation.
  2. Go to Manage Roles.
  3. Select Create Role.
  4. Enter a name, for example:
Hub API DFU Service Role
  1. Add the API.DFU permission.
  2. Save the role.

This role grants permission to perform DFU actions via the Hub API.

Step 2: Create or Select a Group​

Create a group to hold the service and its role assignment.

  1. Open the organisation page.
  2. Go to the Groups section.
  3. Select Manage Groups.
  4. Select Create Group.
  5. Enter a name, for example:
DFU Automation Services
  1. Save the group.

Step 3: Assign the Role to the Group​

Assign the DFU role to the group so that any service in the group inherits the permission.

  1. Open the group.
  2. Select Manage Roles.
  3. Add the role created in Step 1.
  4. Save the changes.

Step 4: Create a Service for Token Exchange​

Create a Connect service to own the client credentials used for token exchange and API calls.

  1. In Connect, create a new organisation service.
  2. Give the service a clear name, for example:
DFU Token Exchange Service
  1. Generate or copy the service credentials:
    • client_id
    • client_secret
  2. Store the client secret securely. It should not be shared, committed to source control, or written to logs.

Step 5: Assign the Service to the Group​

Assign the service to the group created earlier.

Once the service is assigned to the group, it inherits the group’s assigned role and can request tokens with the API.DFU scope.

Step 6: Find the Hub API Service ID​

The audience parameter must be set to the Hub API Service ID for the host computer running the Hub API.

You can obtain this value in either of the following ways:

  • Query the local Hub API and use result.guid.id:
GET http://localhost:43424/api/v1/details

Example response:

{
  "result": {
    "guid": {
      "id": "XXXXXX",
      "computerId": "YYYYYY"
    }
  }
}
  • In Connect, open the target Computer, select Services, then open Hub API. The value shown in the ID field is the Hub API Service ID.

Use this value as the audience parameter.

Step 7: Request an Access Token​

Use the service credentials to request a DFU-scoped access token.

curl -X POST "https://connect.cambrionix.com/api/v1/organizations/<ORG_ID>/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<CLIENT_ID>" \
  --data-urlencode "client_secret=<CLIENT_SECRET>" \
  --data-urlencode "audience=<HUB_API_SERVICE_ID>" \
  --data-urlencode "scope=API.DFU.<HUB_SERIAL>"

Replace:

  • <ORG_ID> with the Connect organisation ID
  • <CLIENT_ID> with the service client ID
  • <CLIENT_SECRET> with the service client secret
  • <HUB_API_SERVICE_ID> with the Hub API Service ID from Step 6
  • <HUB_SERIAL> with the serial number of the target hub

Use --data-urlencode because client secrets may contain characters such as +, /, and =, which must be encoded correctly.

Step 8: Read the Token Response​

A successful response returns an access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "API.DFU.<HUB_SERIAL>"
}

Use the access_token value in Hub API requests.

Step 9: Call the Hub API​

Include the token in the Authorization header:

curl -X GET "http://localhost:43424/api/v1/details" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Troubleshooting​

invalid_client​

The client credentials are not valid.

Check that:

  • The client_id is correct
  • The client_secret is correct
  • The client secret has not been revoked or regenerated
  • The client secret is URL-encoded correctly

invalid_scope​

The requested scope is not valid or not permitted.

Check that:

  • The scope uses the format API.DFU.<HUB_SERIAL>
  • The hub serial number is correct
  • The service is assigned to a group
  • The group has a role with the API.DFU permission

Token request succeeds but Hub API calls fail​

Check that:

  • audience is the Hub API Service ID for the target host computer
  • The token is sent as Authorization: Bearer <ACCESS_TOKEN>
  • The Hub API is running
  • The hub serial in the token scope matches the target hub

Security Notes​

  • Keep client_secret values secure.
  • Do not paste secrets into shared logs, tickets, or chat.
  • Rotate the client secret if it is exposed.
  • Use the minimum required permissions for the service.
  • Prefer a dedicated service for automation instead of using a user account.