Realms — create and manage users

Configuring secure multi-user access in your flespi account.

Realms allow customers to create and manage users in flespi. Each user obtains a token configured according to the realm and user parameters.

How realms work

The main usage is the following: customer creates a realm, then creates some users in it. Then it is possible to obtain a flespi token using user credentials (username and password) or via OAuth. This is all done via public realms API

In order to use realms API, users should use the realm public ID. It is assigned to each realm automatically upon its creation and cannot be changed. Another way is to log in to the flespi panel using user credentials via{REALM_PUBLIC_ID}.

Each realm has two main configuration options: token parameters and subaccount policy.

Token parameters define the default parameters: access (Standard, Master, ACL) and TTL of tokens of each user in the realm. 

  • Default token parameters defined in the realm can be overridden on a per-user basis. Thus, if the user has its own token parameters, the user obtains a token with such parameters; otherwise the user gets a token with default token parameters defined in the realm. 
  • Changing token parameters in the realm will update all the assigned tokens in this realm. While changing the token parameters per user will update the token for this user only.

Subaccount policy defines where each user's token should be created. This basically defines a user's subaccount because each user may create/modify or delete other flespi entities using the provided token if such token allows it to do. Subaccount policy can have the following values:

  • Current — all the users' tokens are created in the same subaccount where realm is created

  • Selected — all the users' tokens are created in the selected subaccount.

  • Auto-created — each user obtains its own subaccount automatically created inside the chosen parent account.

Subaccount policy change is forbidden if the realm has at least one user.

How to create a realm

Open Realms in the Access Management submenu in the left-side menu. Click the “+” button to create a new realm. Specify its Name, provide optional Public information (name, description, and logo), select the Subaccount policy (User's home), and Access level. Click the 'Save + Open' button when you're done.

How to manage user access

To set up a new user account, go to 'Your realm' > Users tab and click the ‘+’ button to create a new one. In the pop-up window, you can specify a username along with a password, and if necessary, change the access level under ‘Token parameters’. Click ‘Save’.

Now you need to share the realm login link with a user. On the 'Your realm' pane, right-click the 'Login' icon in the top-right and select 'Copy link address', or you can use{public_realm_id}. When the user follows the link, the realm authentication page will appear, asking for a username and password. After that, the user will be prompted to save the token for future use.

How to set up SSO authentication

You can allow users to authenticate with a custom Identity Provider, please refer to the following guides:

If you'd like your users to login only with a specific Identity Provider, though having two or more of them set up, you can select a direct link to share. Navigate to 'Your realm' > Users tab. Click on the blue ‘key’ icon for a specific user, and then choose the required Identity Provider from the list. 

When the user clicks on this link, he will be redirected to the Identity Provider authorization page requesting permission to access the account and if the user grants it, the account will be linked with the flespi user account for login. Now, the user can use the direct Realm link as we described above.

Realms API

To perform any operations with the realms, use the realms API

E.g., you can create a user using the following POST request.

curl -X POST  --header 'Authorization: FlespiToken XXXXXXXXX'  -d '[{"name":"","password":"","registration":"immediate"}]' '{realm-selector}/users'


In case of any issue, please navigate to 'Your realm' > Logs tab, pick up an event and click it for details.

Here's the list of event codes explained to help you with further investigation.

CodeEvent description
1200Attempt to log in using invalid user name and/or password
1201Failed to register new user
1220 New identity provider has been added to the realm
1221Identity provider has been removed from the realm
1222Identity provider has been updated in the realm
1225An error has occured during receiving or processing response from the identity provider
1301New user has been created by realm owner
1302User has been updated by realm owner
1303User has been deleted by realm owner
1305New user has registered using 3rd-party account
1310User's password has been re-set by realm owner
1311User has been logged out by realm owner
1312User has been logged out because the realm is blocked
1313User has been logged out because identity provider is blocked
1320User's 3rd-party account has beed successfully linked
1321User's 3rd-party account has been removed by realm owner
1322 User has logged in using 3rd-party account
1350User has logged in using password
1351Failed to create a token after successful log in

See also
How to set up SSO (Single Sign-On) user authentication using GitLab as a custom Identity Provider.
How to set up SSO (Single Sign-On) user authentication using Google as a custom Identity Provider.