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 of 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 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 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:
mqtt is a special topic for MQTT API usage. Along with methods to control MQTT broker API it allows creating tokens that are allowed to subscribe or publish to desired topics. E.g. you can create a token for your customer that is allowed to receive messages only from the related device:
In the IPs whitelist, you can point the CSV list of masks (wildcards are supported) of IP addresses which 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.