Spoke Zone 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

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 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.

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.

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

• You can log into Spoke Zone 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 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.

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 should be a device token that has expired no longer than 12 hours ago.
  • If the request was successful, the API will send a 200 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.
  • Users with super role don't need to provide anything else.
  • Users below super role will need to provide a body in JSON format that includes cpuId.
  • 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.