The evolution of flespi accounts
flespi is a backend platform — it is intended for use inside other products while remaining invisible to its users. It’s like a database management system — everybody knows that a given product is backed by a database system but no-one cares about the specifics. End users need the product features, not the technologies implementing them behind the scenes. Here’s where flespi is relative to the end product users:
Having this concept in mind we initially designed flespi object structure as a flat list — each flespi user has its own private space where everything is living — all its devices, channels, streams, modems, telematics and MQTT messages. No hierarchy. In such case, a Product completely hides the flespi ecosystem from end users. And basically, it is enough for the Product to have just one flespi token to operate with flespi items and services using REST or MQTT API.
But as soon as flespi started to provide more features and ready-to-use technologies like event-driven web application design or it’s further growth into state database concept the Product developer becomes more interested in connecting its users directly to flespi in some application areas. To do less proxying in the Product and concentrate more on the business logic.
To simplify this permissions assignment process we developed flexible token ACLs that allow Product developer to create tokens with specific sets of rights and deliver them directly to end users. Such tokens provide access only to a limited subset of flespi items or functionality — those specified in the token ACL entries. The Product can also allow its end users to access flespi REST/MQTT services directly and rely on the security limitations of the flespi backend. This scheme of work is visualized below:
This works perfectly up to a certain volume of the flespi items — usually in telematics hub we are talking about up to ten thousand devices — and after reaching this volume operating with big flat list becomes complicated and slow at times due to the scale. For example, to access devices state for ten thousand devices via MQTT API you have to receive and handle one hundred thousands of state MQTT messages during subscription call.
These ten thousand devices do not belong to a single end user’s account — they are usually split among different users. Even if all devices relate to the same company, they most likely belong to different internal departments. Speaking in flespi terms, these devices can be split into separate flespi accounts without losing advantages of having them all in the same flat list.
From the user perspective, it is one isolated flespi account and from the Product perspective, it is the same big flat list whenever the Product needs to operate on the whole set of items. Below is the visualization of this concept:
This is the place where flespi accounts hierarchy system steps into the game. And this is the first feature available to our Commercial users only. With this feature, you can create and manage multiple flespi accounts.
The idea behind flespi accounts
The primary role of flespi accounts hierarchy system (we call it the subaccounts feature) is to create multiple accounts with parent-child relations between them.
We support up to four levels of hierarchy.
All items in child accounts are visible to their parent accounts in the flat list.
On the accounts hierarchy scheme shown above the parent account has access to all items, even to items located in child-2-2.
At the same time, child-2-2 has access to its items only and there is no way it can access items located in the sibling accounts.
Same for sub-parent-1 which has access only to own account items and items in child-1-1 and child-1-2 accounts.
To understand which account a given flespi item belongs to, it has a special cid attribute which carries its account ID. And for MQTT messages we add the cid user property of the flespi account to which this message was originally published.
Our subaccounts system is specially designed for telematics use cases. According to the accounts hierarchy shown in the picture above it is possible to create a channel in sub-parent-1 account and create flespi devices in child-1-1 and child-1-2 accounts. Messages received through the channel will be correctly registered in the respective flespi devices (more details here).
Additionally, we perform a special cross-check of device ident uniqueness — e.g. it is not possible to create two devices with the same ident served by one channel even in different flespi accounts. Also, it is possible to create streams and modems in the parent account, and they will have access to all items created in child accounts. Simple and organic.
On top of this, accounts have embedded limits management. It is possible to define a special limit for one of the multiple accounts (as we did with Commercial and Free limits) to control how many flespi resources can be consumed by this account — the number of devices, channels, streams, the volume of API traffic, etc (see KB for more details).
All account counters are controllable. It means that you can give child account users direct access to the flespi panel at the same time being sure that they can only create as many flespi items as you have allowed.
Operating accounts via API
By default, each account can transparently access not only its own flespi items but also all items in its child accounts. Parent accounts can emulate operation from any of its child accounts by specifying a special x-flespi-cid HTTP header in each REST API call. If such header is not specified, all items in the account to which flespi token belongs to and all its subaccounts will be affected.
MQTT sessions created under the parent account token can subscribe to messages generated in a specified flespi account namespace by passing the cid user property during the subscribe request. If cid user property was not specified by default, the session will receive all messages from its own account and all its child accounts. This is an important security consideration for MQTT area of application.
The biggest benefit from using subaccounts feature for MQTT projects is that each account has a dedicated retained messages storage and with multiple accounts and correct topic namings you can make it unlimited thus storing terabytes of data in MQTT retained storage.
For a deeper technical understanding of subaccounts feature, learning on how to control and use counters and limits please consult our Knowledge Base.
***
Subaccounts feature may seem complicated at first, but in reality, it’s very straightforward and logical.
What’s most important is that it allows you to build more flexible and large-scale products than before. We recommend all our users doing any kind of complex developments with flespi to consider these capabilities.
And don’t forget — you are always welcome to shoot us a question and we’ll help you shape an efficient architecture for your application.