- 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. This is the only type of token that provides access to any REST API call that starts from "/platform/", e.g.: realms, grants, webhooks, billing, recycle bin, subaccounts, flespi chat and other platform methods. There are no restrictions for this type of token and we recommend to not use it directly except rare cases when you really need unlimited access to your flespi account.
Standard — a basic token sufficient for working with Telematics entities. Can create, edit and delete any channel, device, stream, plugin, geofence, calculator, asset, modem, cdn and container. Does not have access to tokens, grants, realms, webhooks, subaccounts or to flespi support chat.
ACL — a flexible type of token allowing customization of permissions by module, item type, and specific item ids. We recommend to use ACL tokens by providing to the application only the access level it may need. It is not possible to issue ACL token that provides access to platform-level methods - tokens, grants, realms, webhooks, subaccounts or to flespi support chat.
NOAPI — standing aside type of tokens. These tokens are created and used only for internal purposes. They can be visible in flespi panel, but cannot be used for API requests.
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.
To validate flespi token validity and retrieve its configuration via API you may use GET /auth/info method.
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:
Allowed origins
Note: this option relates only to the request originated from the web browsers.
Allowed origins field gives opportunity to restrict web access for a token to the set of custom web origins. By default any web origin is allowed. In order to set custom origins one has to specify them as an array of strings (wildcards are supported). Here is an example of custom origins: http://localhost:1234, https://*.subdomain.domain, custom7://te?t.example.com.
It is strongly recommended always to allow flespi origins to preserve access to the flespi panel and all the other flespi public projects. This can be done by adding special all flespi origins item via flespi panel or by adding {"preset":"flespi"} object as origins array item via API.
It is also possible to block the use of tokens in the web browsers, i.e. to create a token intended for backend purposes only. In order to do so it is necessary to set allowed origins to an empty array.
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
Platform calculates combined usage of API calls, MQTT messages and REST/MQTT traffic per minute for all tokens of a specific account/subaccount. This combined usage is limited either directly with a limit configured for this subaccount or indirectly by the corresponding plan restrictions for the user.
When flespi platform detects account over-usage it will automatically block its tokens ordering them by the highest corresponding usage counter and leave unblocked only tokens which total combined consumption counter is within limits set for this account. 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.
User can block the token manually by enabling or disabling it.
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
To provide access to device logs, messages and raw traffic via flespi Toolbox create a token with an ACL allowing GET requests to gw/devices/{device-id}. Leave submodules unchecked to enable all submodules.
Open the Toolbox with device with ID=12345 selected via the next link:
https://flespi.io/toolbox/#/devices/12345?token={Token-with-ACL-to-12345-device}.
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/or telemetry submodules:
Open the TrackIt 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
If you receive "invalid or expired access token" error for your REST API calls it means that flespi REST API server is unable to retrieve or validate token that you specified in your REST API call. The most popular reason for this is the "Authorization: FlespiToken XXX" HTTP header missed. The second popular reason is that the header does not contain "FlespiToken" prefix. And the third reason is the flespi token value you specified instead of "XXX" is invalid.
In case of any issues with tokens, check the Logs tab on the token screen:
There you can see all REST API calls that were signed with this token. Including the log events about any changes to this token configuration.
In "Platform Logs" section you can see all REST API calls that were run towards your flespi account with token_id field with the identification of ID of the token used for the request.
In case you can not find the token anymore check "Platform Logs" for "token has been expired and deleted" records. May be the token with short ttl or expiration time was deleted by the system automatically.
If you accidentally deleted token you may restore it from recycle bin within 30 days.