Skip to content
Cloud Connect Docs

Access Tokens

Cloud Connect uses access tokens to authenticate API requests. Whenever a request is made, the token must not only be a real token but have the requisite permissions for making its request; in other words, different levels of tokens have varying levels of permissions.

There are two types of access tokens:

  • User tokens are used for authenticating users when using the site and/or API.
  • Device tokens are used for authenticating devices when they try to access the API to:
    • Retrieve info about themselves (via the devices API)
    • Send and/or receive data over MQTT
    • Upload data files
    • Get and download OTA file updates

Usage

Section titled “Usage”

Whenever an API request is made, a valid access token must be included in its entirety in the x-access-token header.

  • This can be either a device or user token, but keep in mind both are subject to feature restrictions.
  • If using Postman, go to the Headers tab of the request to edit the token.
    • The x-access-token field may have to be manually added if it isn’t there already.

To get your user token:

  1. Navigate to the Settings page via the nav menu.
  2. Click the Extras section in the section selector.
  3. Ensure the token-hotkey feature flag is toggled on.
  4. Press the t key to copy your user token. This hotkey will work anywhere in the site.

To get the token for an MRS-supplied device:

  1. Access the file /etc/spoke-zone/spoke-zone.conf on the device.
  2. The device token is stored in the mqtt_username variable.

Contents

Section titled “Contents”

Go to jwt.io to parse the contents of an access token.

User tokens contain lots of information about the user: username, permissions, organization ID, etc.

Device tokens contain the device ID and MQTT publishing prefix.

Acquisition

Section titled “Acquisition”

User Tokens

Section titled “User Tokens”

You can obtain a user access token via the following methods:

  • You can log into Cloud Connect and press the t key on your keyboard to copy your user token to your clipboard.
    • For this to work, you have to enable the token-hotkey feature flag on the Extras section of the Settings page.
  • You can make a request to the POST /login endpoint.
    • The body of the request should be in JSON format and include password and username variables.
    • If the request was successful, the API will send a 200 response with a JSON object containing the token for that user.

Device Tokens

Section titled “Device Tokens”

You can obtain a device access token via the following methods:

  • When successfully creating a device using the POST /api/v2/devices endpoint a token will be provided in the response.
  • You can make a request to the POST /loginDevice endpoint.
    • The body of the request should be in JSON format and include cpu_id, uuid and token variables.
      • The provided token must be a previously issued device token for the same device.
        • If the token is expired or expires within the next 12 hours, the API validates the provided cpu_id and uuid and issues a new token.
        • If the token is valid for more than 12 hours, the API returns 200 with "Token is valid" instead of issuing a new token.
    • If the API issues a new token, it sends a 201 response with a JSON object containing the renewed token for that device.
  • You can make a request to the GET /api/v2/devices/:id/secrets endpoint.
    • Devices cannot call this endpoint.
      • Requests sent to this endpoint authenticated with a device token will receive an error message.
    • Users with super role don’t need to provide any extra parameters.
    • Non-super users must include the correct cpuId query parameter.
      • Example: GET /api/v2/devices/:id/secrets?cpuId=<device-cpu-id>
    • If the request was successful, the API will send a 200 response with a JSON object containing the cpuId, uuid and a renewed token for the device.