A token is a universal tool to manage access to the flespi platform. Access can be limited by time and by level. Token fields expire and TTL (time-to-live) are used to limit token usage by time. Token fields ACL (Access control list) and IP whitelist are used to control token rights.
You cannot create a token without time limitations. So token MUST expire at some point in time. When creating a token you have to specify either 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 token is considered expired and automatically deleted.
expire field, if not zero, contains explicitly provided UNIX timestamp until which token is considered valid.
ttl field, if not zero, specify the interval in seconds during which token is automatically considered valid since creation (created field) or last time used (accessed field). accessed field is automatically updated whenever you are doing any REST request or have an active MQTT session.
Depending on the access control level tokens can be:
Standard — a basic token sufficient for working with all Telematics hub features (cannot create other tokens).
Master — the almighty token granting access to the flespi platform API and allowing the creation of other tokens.
ACL — a flexible type of token allowing customization of permissions by module and object type.
In ACL you can specify the list of requests allowed to use by the token:
Note: You can also 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:
ACLs for MQTT cannot be configured for topics starting with "flespi/". To allow access to device messages via MQTT, you should create an ACL topic to the "gw/devices" module and explicitly pick the "messages" submodule:
In the IPs whitelist, you can specify the CSV list of masks (wildcards are supported) of IP addresses that are allowed to use the token. Example: 10.100.15.*,192.168.56.1?,127.0.0.1. In case of IP mismatch, the HTTP request will respond with 401 code and error “using token from unauthorized location”; MQTT connection will be closed after failing authorization with the appropriate MQTT code.