Essentials
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 https://flespi.io/#/realm/{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. Realm creation window contains the following fields:
- Name — specify here a unique realm name.
- Public information — optional object with information accessible with realm public ID. Here you can add public name, description text and logo picture URL.
- Token parameters — realm default token parameters as described above
- User's subaccount — subaccount policy described above
How to create a user?
After realm creation, you can add users in it. To do that, just open a realm and go to Users tab. Here, you can create users by clicking the "+" button. You can choose how to create a user: immediately or with confirmation.
- Immediately created users can log in to the realm right after their creation. Realm owner should specify user password during creation.
- Users created in confirmation mode are created without password and cannot log in to the realm. They should obtain a confirmation link for password assignment or OAuth account linkage from the realm owner. Those links can be obtained via "key" icon on the user card.
Realms API
To perform any operations with the realms, use the realms API.
Troubleshooting
[COMING SOON]