16 August, 2023

Keeping accounts organized and secure: making sense of subaccounts, realms, grants, and tokens

A figurative clarification of the uses and purpose of the flespi account and access management entities.

Flespi now features quite a few entities related to accounts management, permissions management, and access control — subaccounts, realms, grants, and tokens. The goal of this article is to clarify the purpose of each of these entities and explain how they can work together efficiently to ensure secure and well-structured flespi account operation.

Let’s start with some figurative stuff to draw a clear picture in our heads.


We all work in an office (or at least used to work there), so the following analogies should be familiar:

  • Account — company’s office

  • Subaccount — room in the office

  • Token — key to the office, room, or drawer

  • Realm — a bunch of keys for different employees that can open different rooms and/or drawers

  • Grants — keys from a colleague’s room

With these images in mind, let’s explore each of the items in more detail to understand its scope of application.


Keywords: access, permissions, ACL

Situation: A new employee comes to the company. He is first given access to general facilities, and his workplace. Later he may be granted access to important financial documents, meeting rooms, or the corporate car.

Token is the “key” to an entire flespi account or some of its items only. You can give a key to your colleague to check if you forgot important papers on the table. Or you can give a key to a colleague and ask them to print some papers for you while you are staying home sick.

Flespi has three types of tokens:

  • Master — you enter the God-mode — you can do everything with the account, manage any items, check billing, statistics, create other tokens, chat with us, and more.

  • Standard — you can do everything, but you can’t create other tokens and can’t access admin tools (billing, stats, chat, realms, etc.).

  • ACL — you can only perform a specific set of actions on a specific set of items. This is the easiest option to share access either to a subaccount, or your account, or to specific items in them.

All in all, tokens:

  • Are required to log in to the flespi platform

  • Define the scope of items and actions available to the platform user

  • Determine how long the access will be available

The in-depth technical guide on tokens is available here.


Keywords: hierarchy, projects

Situation: Two teams in the company work on two unrelated projects. They have full access to all the information on their project, but have to access to the other team’s project. Both teams can use the company’s last year reports as the basis for their analytics.

Subaccount is an isolated subset of items, access to which is restricted to the subaccount owner, parent account(s), and trusted subaccounts (via grants). Flespi allows 4 levels of subaccounts. Subaccounts apply limits to define what capabilities and with what restrictions the user can act.

All in all, subaccounts:

  • Allow building a hierarchy of accounts for a company by properly allocating permissions for separate projects, departments, teams, roles (see more here).

  • Ensure desired level of isolation and security.

  • Enable convenient development of large-scale projects.

The in-depth technical guide on subaccounts is available here.


Keywords: shared access, ACL

Situation: You ask your colleague to fill in for you and say “here’s the key from my room, You can use my printer to print the docs you need, and you can also take some pastries from the box”

Grant is a sharing mechanism that allows configuring special permissions to access and/or manage specific items in otherwise inaccessible subaccounts or such subaccounts as a whole. For, instance, you want several child subaccounts to use a single calculator in a parent account. Or, you want to grant read-only access to device logs and messages for a hardware engineer to debug.

All in all, grants:

  • Enable extended access sharing between unrelated subaccounts (something that tokens cannot do)

  • Allow re-using higher level items to optimize resource utilization

The in-depth technical guide on grants is available here.


Keywords: access management, users, OAuth, SSO

Situation: Imagine a security department that issues electronic programmable keys and passes. They can change access permissions for the entire department in a few clicks, they can block access any time. If you give ten employees keys from the same room — it’s like having them work in an open-space with a shared printer ;)

Realm is a user management automation mechanism. You create an application/realm for your colleges (just a named entity), have a link to this app, create users (name/password which are unique to this app) and it will automatically create subaccounts, tokens, grants per your configuration. Realms support OAuth, can be used for corporate or social network SSO, let you customize the login screen with your logo, and more.

All in all, realms:

  • Automate and simplify token/user management

  • Enable corporate or social network SSO

  • Allow login dialog white-labelling

The in-depth technical guide on realms is available here.

Putting the pieces together

As you might have noticed, the four types of items discussed above can compliment each other to ensure secure and well-organized accounts and permissions structure for projects of any complexity.

Below is the summary table that consolidates the functions that each item brings:



Grant access to flespi account, subaccount, specific items


Share access to flespi account, subaccount, specific items with a colleague


Make specific items in one subaccount visible from another subaccount


Enable shared use to specific items


Allow an unrelated subaccount to manage specific items in another subaccount


Create and manage users


Automate access management (tokens, subaccounts, grants creation)


Enable single sign-on (SSO) for an organization


Support OAuth


Isolate projects, teams, departments


Ensure security and structure for hierarchical large-scale projects



Flespi is constantly developing to deliver elaborate access management mechanisms and make our customers experience with them seamless and rewarding. We invite you to explore the capabilities offered by following the links above, and shoot us specific questions in the chat if stuck.