Subaccounts — dedicated flespi accounts for telematics projects

Building a flexible and safe hierarchical accounts structure for enterprise-level solutions.

Essentials

The primary role of subaccounts is to create multiple accounts with parent-child relations between them

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:

  1. Each flespi item (channel, device, subaccount, etc.) has ONE owner defined by the cid parameter (which corresponds to a particular customer_id).

  2. Each account has ONE parent defined by the owner_id parameter. Master account’s owner_id=0. Each account (except the fourth-level accounts) can have multiple child accounts.

  3. A parent account can MANAGE all its child accounts’ items.

  4. 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.

flespi parent child accounts

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).  

subaccounts use parent channel

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.

isolated subaccount setup

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.

parent stream flespi subaccounts

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.

devices use modems

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?

  1. Log in to the flespi panel
  2. Navigate to the Access management item in the left-side menu, pick the Limits sub-item, and click "+" to create a new limit:
    create new limit in flespi
    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.
  3. 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.
    configure a new limit in flespi

  4. Switch to the Subaccounts sub-item in the Access management menu and click "+" to create a new subaccount:
    create a subaccount in flespi

  5. Give it a name and assign a limit to it:
    assign limit to subaccount in flespi
    Note: if you haven’t created a limit yet, you can do it later and then assign the new limit in the subaccount settings.

  6. 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.

  7. Log in with the new subaccount by clicking the Login button on the token card:
    log in with subaccount in flespi
    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>.

  8. 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).
    change subaccount credentials in flespi
    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.

move flespi device from account to subaccount

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:

flespi parent child accounts

  1. use Ctrl+click to select the desired devices
  2. click on the purple "Move to subaccount" button
  3. 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.

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:

  1. Perform a regular REST API call with Token DEF, which belongs to Child 1

  2. 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:

subaccount logs