Token — access key to the flespi platform

 How to create, use, and manage tokens in flespi.
tokens

Essentials

Flespi token is a 64-byte randomly generated key-string used to access the data on the flespi platform via API. 

In HTTP REST API a token is used in the “Authorization” header. 

In MQTT API a token is used as an MQTT connection Username.

Token types

Depending on the access control level tokens can be:

  • Master — the admin-level token granting full control over a flespi account including the platform API and creation of other tokens.

  • Standard — a basic token sufficient for working with all Telematics hub items (cannot create other tokens).

  • ACL — a flexible type of token allowing customization of permissions by module, item type, and specific item ids.

How tokens work

As soon as you authorize at https://flespi.io, the platform will create a token for your session that will expire shortly after the session ends. To use a token in API calls you need to create a new one with the correct expiration date and access control parameters. 

What’s not allowed is forbidden. ACL mechanism only grants access — by default all actions are denied for the token with enabled ACL and any action not explicitly specified in ACL is forbidden.

Tokens expiration management

You cannot create a token without time limitations. The token MUST expire at some point in time. 

When creating a token you have to specify either the TTL or expire parameter. Or both. Token will be considered valid if any of these fields is considered valid. Once both fields are no more valid, the token is considered expired and will be automatically deleted.

flespi token expiration

The expire field, if not zero, contains an explicitly specified UNIX timestamp until which the token is considered valid.

The ttl field, if not zero, specifies the interval in seconds during which the token is considered valid since creation (created field) or last time used (accessed field). The accessed field is automatically updated whenever you perform any REST request or have an active MQTT session.

How to create a token?

  1. Log in to the flespi panel
  2. Navigate to Tokens in the left-side menu and click the "+" button in the bottom right corner to add a new token:
    create new token
  3. You will be offered to use a token template. If you don't want to be offered templates anymore, check the "Don't auto-offer templates anymore" and close the dialog. Otherwise pick the suitable template:
    token templates list
  4. If you chose not to proceed with a template, fill in the name (info field) for a new token, pick the proper access type depending on the needs, configure it, and click Save:
    configure flespi access token

Also, check our How to create a flespi token video on YouTube.

Tokens API

To perform any operations with the tokens, use the tokens API.

Advanced use

Submodules

You can specify ACLs for specific submodules within a module, e.g. you can grant access to the device settings while not allowing to modify the device itself:

flespi token acl submodule

IP whitelist

In the IPs whitelist field, you can specify the CSV list of masks (wildcards are supported) of IP addresses that are allowed to use the token, e.g. 10.100.15.*, 110.160.56.1?, 182.15.48.5. 

In case of an IP mismatch, the HTTP request will respond with a 401 code and error “using token from unauthorized location”; the MQTT connection will be closed after failing authorization with the appropriate MQTT code.

Sharing access

Create login/password pairs

To define your own set of users to authorize into flespi.io please look into realms.

Token for a subaccount

You can generate a token for a specific subaccount to allow only the person (partner, colleague, client) responsible for the subaccount to manage it (remember that the top-level account, which is presumably yours, always has the rights to manage its child subaccounts).

To create a token for a specific subaccount, check the Create for subaccount checkbox at the top of the dialog and pick the subaccount from the dropdown list:

create token for subacccount

If you create a token for a subaccount via REST API, use the x-flespi-cid header in the following POST request: https://flespi.io/docs/#/platform/tokens/post_customer_tokens.

Token for the flespi panel

The flespi panel can be operated under Master, Standard, or ACL token:

  • With a Master token you get admin access and full control over the flespi account.
  • With a Standard token, you can manage all the Telematics hub items, but will not see the items counters, won’t be able to use the Helpbox chat, and won’t be able to control tokens/subaccounts/limits. Standard token should be enough for most users — they will be able to manage the account’s items but not have the admin privileges to change permissions and subaccounts structure.
  • With an ACL token, you can customize which items will be allowed access and which not (this refers only to the items in the Telematics hub section).

flespi panel access token

Then use the Login with token option to open the flespi panel with this token:

Token for device groups

To give access only to devices assigned to groups, you need to use the "in-groups" selector when creating an ACL token:

acl token for device groups

Token for Toolbox

Create a token with an ACL allowing GET requests to gw/devices/{device-id}:

acl token for toolbox

Token for Setbox

Create a token with an ACL allowing GET requests to gw/devices/{device-id} and explicitly allow access to the following submodules: GET, PUT, and DELETE for the settings submodule, POST for the commands submodule, и GET, POST, and DELETE for the commands-queue submodule, and POST, GET for the sms submodule to be able to change device configuration:

acl token for setbox

Token for TrackIt

Create a token with an ACL allowing GET requests to gw/devices/{device-id} and explicitly allow GET permissions for the messages and telemetry submodules:

acl token for trackit

Open the TrackIt tool via the link
https://flespi.io/trackit/#/login/{Token-with-ACL-to-12345-device}/devices/12345.

Token for device manufacturer's support

In order to provide device manufacturer support team access to the device in flespi including the access to its raw traffic create a token with an ACL allowing GET requests to gw/devices/{device-id} and specify token expiration time to revoke access automatically after a certain period of time.

Share to the manufacturer the link in form: https://flespi.io/#/token/{TOKEN}/devices/{DEVICE-ID}. This will open flespi.io panel with device page and provide access to device manufacturer support both to parsed device messages and raw traffic. If desired you may provide manufacturer with an access to bidirectional query the device remotely via commands and settings - just add more access to the token by following token for Setbox instructions.

Token for MQTT access to messages

To allow access to device messages via MQTT, you should create an ACL token to gw/devices and explicitly pick the messages submodule:

flespi token acl messages mqtt

Important! ACLs for MQTT cannot be configured for topics starting with "flespi/".

Troubleshooting

In case of any issues, check the Logs tab on the token screen:

flespi access token logs