- Essentials
- How subaccounts work
- Usage scenarios
- Limits for subaccounts
- How to create a subaccount?
- How to move devices from account to subaccount?
- Sharing access between unrelated subaccounts
- Blocking subaccounts
- Subaccounts API
- Troubleshooting
Essentials
Subaccounts are designed to create multiple accounts with parent-child relations between them.
Each flespi entity(device, channel, ...) has cid property which defines the ID of account they belong to.
In flespi panel UI entities which cid is not the same as customer ID of currently logged in user (they belong to different account ID, usually to subaccount) have orange "cid: XXXX" account identification in the top-right corner of their card. Entities without such identification belong to the same account as currently logged in user(token).
Subaccounts support up to four levels of hierarchy.
How subaccounts work
- Parent (master) account has access to all items (even to items located in the subaccount 1-3-2).
- Subaccount 1-3 has access only to its own account items and items in subaccount 1-3-1 and 1-3-2.
- Subaccount 1-3-2 has access to its items only and there is no way it can access items located in the sibling accounts.
Important! 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.
You must define limits for subaccounts to control how many flespi resources they consume — the number of devices, channels, streams, the volume of API traffic, etc (see the dedicated section below).
Key rules describing relations in the accounts hierarchy:
Each flespi item (channel, device, subaccount, etc.) belong to a specific customer account. You can identify to which customer account entity belongs to by checking its cid property which contains the value of particular customer account ID.
Each customer account has ZERO or ONE parent. The parent is defined by the owner_id parameter in customer account. If owner_id=0 it means that customer account has no parent and root account in the hierarchy. Each customer account (except the fourth-level accounts) can have multiple child accounts.
A parent account can MANAGE all its child accounts’ items.
Child account items can USE parent account objects.
Clarification: the account can manage the item from its “branch” of the hierarchy tree only, and the child item can use the parent’s items from its “family” of parents up to the master account only.
Usage scenarios
Devices USE channel
Devices USE a channel to receive messages and send commands over channel connections.
Application: parent account can group devices. In this case, devices can’t have the same ident (e.g. it is not possible that two companies connect a device with the same IMEI to one host:port).
Note! If you want to have a fully isolated project for a certain subaccount, you can move the channel down by hierarchy. In such a case even if the device connects to the common channel in the root account, it won’t affect the subaccount. In the scheme below “common channel” and “isolated channel” work over the same protocol.
Channels and devices USE stream
The stream can subscribe for messages from the child channels and devices.
Application: only the parent account can manage stream subscriptions and turn on or off subscriptions for specified channels or devices.
Devices USE several modems to send SMS
The child account uses its own modem to send settings to devices and if it fails to deliver the message, then the parent account modem tries to send the SMS. (Subaccount is created without a modem, so by default, it uses the parent account's modem.)
Application: The parent account allows the subaccount to use its own SMS service account but guarantees delivery of the SMS by backing up the modem if the subaccount modem is not working properly.
Note: Channels use modems to send channel commands via SMS, so all of the above applies to channels as well.
Calculators are assigned to devices
You can assign a calculator from the parent account to devices in a child subaccount. To get intervals from the calculator, subscribe to the flespi/interval/gw/calcs/{calc_id}/devices/{device_id}/{event_type} topic from the parent account.
Important! If you subscribe to the flespi/interval/gw/calcs/{calc_id}/devices/{device_id}/{event_type} topic from the subaccount, you won't receive messages, because the subaccount has no access to a calculator in the parent account.
Plugins are assigned to devices
You can assign a plugin from the parent account to devices in a child subaccount. Important: you can assign the plugin to subaccount devices only from the parent account. BTW, you can also create devices for subaccounts directly from the parent account — just select a proper subaccount in the "Create" dialog.
Alternatively, from the parent account you create groups in each subaccount and assign the plugin to these groups. Then, when the user in the subaccount creates devices, he will need to assign them to the group. And the plugin will automatically be applied to all devices in the group. This will be a one-time operation and will not require repetitive actions from the parent account owner.
Limits for subaccounts
A parent account can limit the platform resource usage for each subaccount. To do so the parent account creates a limit that defines the resources available for a subaccount and assigns this limit to the specified subaccount.
Exceeding the limits will take the same effect on subaccounts. The common rule for limits hierarchy is that the parent is responsible for all its children, so if all child accounts combined exceed the limits for the parent account, the parent account will be blocked (along with all its subaccounts). For the master account, it means that billing is calculated as a sum of all subaccounts the platform use.
Here are some examples of the resources you can limit:
prohibit new channels and streams creation by subaccount (as channels and streams are the most expensive flespi items)
limit the subaccount’s use of channel and API traffic to prevent the whole master account from being blocked because of inappropriate platform usage
limit the subaccount’s SMS usage as SMS service incurs extra charges
create a limit according to your billing maximum rate and operate with the flespi platform from the subaccount only to avoid extra charges. As the flespi pricing model is “pay-as-you-use”, you can exceed your expected platform usage due to a coding mistake which will result in a bloated monthly bill. So working with limits will allow you to control the usage automatically.
The detailed description of commercial accounts limitation is described on the pricing page.
How to create a subaccount?
- Log in to the flespi panel
- Navigate to the Access management item in the left-side menu, pick the Limits sub-item, and click "+" to create a new limit:
Note: if you don’t see the Access management item in the left-side menu, go to the Preferences menu in the bottom left corner and enable the respective toggle in the Appearance tab. Configure a new limit. You can set up restrictions on the use of specific resources for the subaccount. If you leave default values (-1) for certain parameters, they will be limited by the available resources of the parent account.
Switch to the Subaccounts sub-item in the Access management menu and click "+" to create a new subaccount:
Give it a name and assign a limit to it:
Note: if you haven’t created a limit yet, you can do it later and then assign the new limit in the subaccount settings.Create a new token for the subaccount in the Tokens menu. Pick the necessary subaccount from the list on the “Create for” parameter. Pick the Master type in the access parameter. Set a TTL or expiration date if needed.
Log in with the new subaccount by clicking the Login button on the token card:
Note: if you want to share the login link with someone, you can either right-click on the Login button and select Copy link address or copy the token and paste it at the end of the following URL: https://flespi.io/#/token/<TOKEN_GOES_HERE>.Set credentials. Once you log in, we recommend changing the subaccount settings. Set a self-explanatory name, and most importantly, set the email and password, so that a person using this subaccount could log in to the flespi panel with their own credentials (not with a token).
Note: you as the owner of the parent account will always be able to log in to this subaccount using a token.
How to move devices from account to subaccount?
You often start with a Free account or a default account in your Commercial plan. Later on, you may want to group your devices by project, by customer, by manager, etc. Flespi offers subaccounts to organize such grouping. Now you need to move the already created devices from the parent account to a subaccount.
You need the following method for that: https://flespi.io/docs/#/gw/devices/put_devices_dev_selector_cid.
Just specify the ids of the devices you need to move and the cid of the subaccount to move them to.
You can copy the curl to execute from the terminal or execute the request right in the documentation (beware — it will perform the actual moving).
Important requirements
The device must not be moved/created within the last 60 seconds.
If the device is assigned to a calculator, the new account must have access to this calculator.
If the device is assigned to a stream, the new account must have access to this stream.
If the device is assigned to a plugin, the new account must have access to this plugin.
There should be no MQTT state topic (flespi/state/gw/devices/{device-id}/…) related to the device with a timestamp of more than 60 seconds from the present (especially actual for telemetry values).
Moving devices in UI
flespi panel also features the functionality to move devices between accounts:
- use Ctrl+click to select the desired devices
- click on the purple "Move to subaccount" button
- select the target subaccount from the drop-down list and click Move
Moving channels
You can also move channels from account to subaccount using the following request method: https://flespi.io/docs/#/gw/channels/put_channels_ch_selector_cid.
There is no possibility to move calculators, streams and plugins between subaccounts but you may use grants to provide access to them from another account.
Sharing access between unrelated subaccounts
Grants allow one subaccount to get access to the instances in another subaccount that is not directly related to it (has no parent-child relation with it). Grant can be issued to the subaccount as a whole, to ALL instances of a given type (e.g. channels, devices, etc.), or to specific instances only. Explore more about grants here.
Blocking subaccounts
You block subaccount by disabling it (with PUT {"enabled": false}). Disabled subaccounts act similarly to assigning them a limit, where everything is restricted. When subaccount is disabled all its elements are disabled and become interoperable as well - devices, channels, streams, tokens, child subaccounts and so on.
Subaccounts API
To perform any operations with the subaccounts, use the subaccounts API.
HTTP API
Parent accounts can emulate operations from any of their child accounts by setting a special x-flespi-cid HTTP header in each REST API call. Without such a header, the request will operate with instances that belong to the branch of subaccounts for the account with the given authorization token. Consider the following account configuration: master account has two subaccounts, each having separate sets of devices. If the master needs to perform an HTTP REST API call that operates with a set of devices that belong to Child 1, there are two ways to do so:
Perform a regular REST API call with Token DEF, which belongs to Child 1
Perform REST API call with master account Token ABC, adding the header: x-flespi-cid: 11, e.g.
curl -X GET --header 'x-flespi-cid: 11' --header 'Authorization: FlespiToken ABC’ 'https://flespi.io/gw/devices/all'
Important note: subaccount ID is the number contained inside its "id" property, while "cid" property for any flespi object contains the ID of its parent's account. I.e. for a subaccount "cid" equals the customer owner_id. So you need to use the value inside the "id" field of the subaccount to operate on its level.
MQTT API
MQTT sessions created under the parent account token can subscribe to messages only generated on a specified flespi account’s namespace by passing the cid user property during subscribe request. If the cid user property was not specified by default, the session will receive all messages from its own account and all its child accounts. User properties can be used beginning from MQTT version 5.0. You can easily test this feature with MQTT Board.
Troubleshooting
Logs for subaccounts are available on the Logs tab for the subaccount:
If you receive "access denied to cid=0" error reason in the response of your REST API calls ensure that you specified correct value in 'x-flespi-cid' header. It should be positive number that corresponds to subaccount ID from which you want to perform the API call and your token should have acess to that subaccount. If you are using ApiBox to construct or test flespi REST API call it may be that you accidentally included this header in the API call with default zero value. In that case just uncheck 'x-flespi-cid' header or specify correct cid value in it.