Skip to content
Spoke Zone Docs

Access Tokens

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

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

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

User Tokens

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

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.