- Essentials
- Token types
- How tokens work
- Tokens expiration management
- How to create a token?
- Tokens API
- Advanced use
- Sharing access
- Troubleshooting
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. E.g. a token with ACL to create devices (method POST), will have no read access (method GET) to devices, even for those, created using this token.
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.
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?
- Log in to the flespi panel
- Navigate to Tokens in the left-side menu and click the "+" button in the bottom right corner to add a new token:
- 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:
- 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:
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:
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.
Blocking tokens
Tokens can be blocked automatically by the platform if you overused REST API calls, traffic or MQTT messages set by the account's limit or tokens can be blocked manually by disabling them (with PUT {"enabled": false}). When flespi platform detects account over-usage it will automatically block only tokens with the highest corresponding usage counter while other tokens will continue to operate as usual. Thus, automatic blocking effectively cuts off only problematic tokens, while other tokens continue to operate as normal.
Blocking a token just disables platform access using this token and does not affects the operation of other entities within subaccount.
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:
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).
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:
Token for Toolbox
Create a token with an ACL allowing GET requests to gw/devices/{device-id}:
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:
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:
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:
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:
