We'll post here all the changes regarding platform API.

We are updating the ACL API. The goal is to make it up to date with the current REST API and remove "GET method inheritance" constraint for submodules. All the changes will be done in several steps. Step 1 (13 Feb 2020) ACL entry for gw/protocols becomes deprecated. Since this time access to protocols list is always open for ACL tokens. You may still use ACL entries for gw/protocols but you will receive an error message for every API call with such entry in addition to data reply. In 4 weeks (11 Mar 2020) gw/protocols entry will be removed from API. We will: disable GET method inheritance for submodules and allow specifying GET method for submodules add new submodules for ACL entries to correspond with the current REST API drop gw/protocols support for ACL entries Here is an example with gw/devices entry to show the scope of changes. Old API: specified GET method was inherited by submodules supported submodules: "settings", with PUT and DELETE methods (no GET) New API: specified GET method is NOT inherited by submodules supports the following submodules (the exact mapping of the current REST API): NEW "calculate", with POST method support NEW "logs", with GET method support NEW "messages", with GET method support "settings", with GET NEW , PUT and DELETE methods support NEW "snapshots", with GET method support NEW "telemetry", with GET method support If your ACL contains entries with enabled GET method and enabled submodules, these entries are expanded to keep backward compatibility. Here is an example. Old version: { "uri": "gw/devices", "ids": "all", "methods": ["GET"], "submodules": [ { "name": "settings", "methods": [] } ] } if("undefined"!==typeof hljs)hljs._ha();else if("undefined"===typeof hljsLoading){hljsLoading=1;var a=document.getElementsByTagName("head")[0],e=document.createElement("link");e.type="text/css";e.rel="stylesheet";e.href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.7.0/styles/default.min.css";a.appendChild(e);e=document.createElement("script");e.type="text/javascript";e.onload=function(){var d={},f=0;hljs._hb=function(b){b.removeAttribute("data-hljs");var c=b.innerHTML;c in d?b.innerHTML=d[c]:(7 Patched version: { "uri": "gw/devices", "ids": "all", "methods": ["GET"], "submodules": [ { "name": "logs", "methods": ["GET"] }, { "name": "messages", "methods": ["GET"] }, { "name": "settings", "methods": ["GET"] }, { "name": "snapshots", "methods": ["GET"] }, { "name": "telemetry", "methods": ["GET"] } ] } if("undefined"!==typeof hljs)hljs._ha();else if("undefined"===typeof hljsLoading){hljsLoading=1;var a=document.getElementsByTagName("head")[0],e=document.createElement("link");e.type="text/css";e.rel="stylesheet";e.href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.7.0/styles/default.min.css";a.appendChild(e);e=document.createElement("script");e.type="text/javascript";e.onload=function(){var d={},f=0;hljs._hb=function(b){b.removeAttribute("data-hljs");var c=b.innerHTML;c in d?b.innerHTML=d[c]:(7 Explicitly mentioned or omitted GET method for the specified submodule also opens or closes access to the corresponding MQTT flespi topics: every "log" submodule regulates corresponding "flespi/log/..." topic gw/channels and gw/devices "messages" submodule regulates corresponding "flespi/message/..." topic gw/channels "commands-queue", "connections" submodules regulate corresponding "flespi/state/gw/channels/{channel-selector}/{submodule}/#" topics gw/devices "telemetry", "settings" submodules regulate corresponding "flespi/state/gw/devices/{device-selector}/{submodule}/#" topics gw/streams "channels", "devices" submodules regulate corresponding "flespi/state/gw/streams/{stream-selector}/{submodule}/#" topics gw/calcs "devices" submodule regulates corresponding "flespi/state/gw/calcs/{calc-selector}/devices/#" topic We will also enable sending error messages for the following cases: ACL REST API usage in an old manner: i.e. won't specify GET method for a submodule when there is GET method specified for an entry sending GET queries to the resource with implicitly enabled GET access (i.e. GET method is inherited for the corresponding submodule in ACL) This may trigger false positive errors, but we believe it's better to notify as many users as possible before the final API change. Step 2 (11 Mar 2020) We stop sending error messages in response to the REST API calls and disable the GET method inheritance for submodules. From this moment all GET requests are denied unless ACL explicitly allows them. All the specified gw/protocols entries will be removed from ACL as unnecessary.

flespi REST API gateway has been enhanced with additional feature: whenever we have a REST request from token that specified subaccount with valid cid (e.g. server process simulates itself as a subaccount with x-flespi-cid HTTP header) we log REST API call quantity and traffic for given subaccount. Previously the call has been always logged exactly under the account its token belong to. This update is related to users of subaccounts management via API and can be used for limiting amount of calls or traffic subaccounts can use.

We have moved warnings about deprecated REST API usage from "errors" array into the new "warnings" array. If you are performing REST API queries in deprecated format then you will start receiving responses like the following one: { "result": [...], "warnings": [ { "reason": "Sample warning message" } ] } .

Today we have installed update for tokens ACL according to the schedule mentioned in this thread ( omol ). Now all the GET method inheritance for submodules is disabled and you have to open it explicitly if it is necessary for your workflow. All your tokens created and modified before the first update (13 February 2020) will continue work as expected. This change affects only tokens created/modified during this four-week period (13 February - 11 March).

In order to optimize logs storage we will remove some parameters from a generic log message. Parameters list are below: event_origin - parameters origin_id and origin_type allow you to restore it event_text - textual representation of event_code Changes will be applied at march 30th.

adsa installed today. The internal log subsystem has also been reorganized to reduce the log selection delay. If you notice incorrect log behavior, please contact us.

We introduced slight non-blocking change to the tokens configuration. First of all we added created field which shows their creation time. For all existing tokens for which we do not know the time they were created, we specified last accessed time as creation time. Second - we do not update expire field anymore automatically for tokens with ttl specified. We just softly calculate validity state for the token by using both explicitly specified expire field and dynamically calculated created / accessed + ttl fields. For more information about time control please refer to the knowledge base .

We are announcing some changes in token ACLs: ACL entries "gw" and "storage" will be removed. You should use item-specific entries (gw/channels, storage/containers, etc) When you specify access for an item and also specify access for its submodules, then access for non-mentioned submodules is denied. If you don't specify access for submodules then ACL behavior will remain unchanged. All the ACLs created before 8 October 2020 will be updated to new format automatically. Almost all the flespi users will not be affected by these changes since their usage pattern suits for old and new approaches. When? Starting from today ( 24 September 2020 ) you will receive warning messages if your ACL usage is deprecated. On 8 October 2020 we will update all the tokens and apply changes mentioned above. Details Abandoning "gw" and "storage" items 99% users do not use this global items. These items have very wide scope and are not applicable for real life use cases. It is decided to remove them. Moving from implicit submodules access to explicit only approach How does it work now? When you specify access for an item and do not specify access for its submodules, then submodules access is defined by their item (i.e. access is implicitly inherited). Example ACL entry: { "uri": "gw/channels", "ids": "all", "methods": ["GET", "PUT"], "submodules": [ { "name": "messages", "methods": ["GET", "DELETE"] } ] } if("undefined"!==typeof hljs)hljs._ha();else if("undefined"===typeof hljsLoading){hljsLoading=1;var a=document.getElementsByTagName("head")[0],e=document.createElement("link");e.type="text/css";e.rel="stylesheet";e.href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.7.0/styles/default.min.css";a.appendChild(e);e=document.createElement("script");e.type="text/javascript";e.onload=function(){var d={},f=0;hljs._hb=function(b){b.removeAttribute("data-hljs");var c=b.innerHTML;c in d?b.innerHTML=d[c]:(7 explicitly allows to GET, PUT /gw/channels/{selector} explicitly allows to GET, DELETE /gw/channels/{selector}/messages implicitly allows to GET, PUT any non-specified submodules /gw/channels/{selector}/{logs, connections, etc} How will it work? When you specify access for an item and also specify access for its submodules, then access for non-mentioned submodules is denied. Example ACL entry. { "uri": "gw/channels", "ids": "all", "methods": ["GET", "PUT"], "submodules": [ { "name": "messages", "methods": ["GET", "DELETE"] } ] } if("undefined"!==typeof hljs)hljs._ha();else if("undefined"===typeof hljsLoading){hljsLoading=1;var a=document.getElementsByTagName("head")[0],e=document.createElement("link");e.type="text/css";e.rel="stylesheet";e.href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.7.0/styles/default.min.css";a.appendChild(e);e=document.createElement("script");e.type="text/javascript";e.onload=function(){var d={},f=0;hljs._hb=function(b){b.removeAttribute("data-hljs");var c=b.innerHTML;c in d?b.innerHTML=d[c]:(7 explicitly allows to GET, PUT /gw/channels/{selector} explicitly allows to GET, DELETE /gw/channels/{selector}/messages denies all the request to non-mentioned modules (i.e. does not allow what is not mentioned) How to avoid warnings? If you need to use some submodules in ACL and you want to avoid warnings, then you may explicitly deny access for all unused submodules. Let's assume you need to GET, PUT all streams and assign devices to them. Then you might have the following ACL entry: { "uri": "gw/streams", "ids": "all", "methods": ["GET", "PUT"], "submodules": [ { "name": "devices", "methods": ["GET", "POST", "DELETE"] } ] } if("undefined"!==typeof hljs)hljs._ha();else if("undefined"===typeof hljsLoading){hljsLoading=1;var a=document.getElementsByTagName("head")[0],e=document.createElement("link");e.type="text/css";e.rel="stylesheet";e.href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.7.0/styles/default.min.css";a.appendChild(e);e=document.createElement("script");e.type="text/javascript";e.onload=function(){var d={},f=0;hljs._hb=function(b){b.removeAttribute("data-hljs");var c=b.innerHTML;c in d?b.innerHTML=d[c]:(7 To avoid receiving warnings you may explicitly deny access to "channels" and "logs" submodules: { "uri": "gw/streams", "ids": "all", "methods": ["GET", "PUT"], "submodules": [ { "name": "devices", "methods": ["GET", "POST", "DELETE"] }, { "name": "channels", "methods": [] }, { "name": "logs", "methods": [] } ] } if("undefined"!==typeof hljs)hljs._ha();else if("undefined"===typeof hljsLoading){hljsLoading=1;var a=document.getElementsByTagName("head")[0],e=document.createElement("link");e.type="text/css";e.rel="stylesheet";e.href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.7.0/styles/default.min.css";a.appendChild(e);e=document.createElement("script");e.type="text/javascript";e.onload=function(){var d={},f=0;hljs._hb=function(b){b.removeAttribute("data-hljs");var c=b.innerHTML;c in d?b.innerHTML=d[c]:(7

omol We are deferring the final update to 12 October 2020

Some REST API methods like PUT gw/devices or GET gw/devices/messages, etc., multiplied the API call count by the number of items affected. Thus, we tried to protect the platform from overload. But this method was not obvious to platform consumers, so we decided to simplify it - now any REST API call increases the total counter by 1.

[Changelog] flespi platform API

adsa

We are excited to introduce a highly requested feature in today's update. Managing projects with complex architectures, numerous subaccounts, and intricate token systems can be challenging. In response to user feedback, we've now made it easier for you to temporarily suspend subaccount activities.

Previously, achieving this required setting a completely restricted limit for the subaccount. However, with the latest update, you can now simply toggle the ON/OFF switch for the desired subaccount or token. Notably, disabling this option will recursively affect all nested subaccounts.

REST API method to disable subaccount:
PUT /platform/subaccounts/{subaccount-id}
Payload: {"enabled": false}

Similarly, to disable a token, use the following REST API call:
PUT /platform/tokens/{token-id}
Payload: {"enabled": false}

omol

We have lifted "experimental" restriction flag from Realm and Identity Provider entities. You can find them in "Access Management" tab in the side menu:

Realms allow you arrange per-user token management. The most obvious application is to provide multi-user access to your flespi account.

Identity providers represent configuration of 3rd-party identity management solutions. We support work with OAuth 2.0 and OpenID Connect identity providers. Using identity providers you can link accounts of any organization to flespi realm users.

In the nearest future we will publish more details on how these features can be used together. If you want to try them now and encounter any questions then don't hesitate to ask in our support chat.

adsa

We have removed a parameter called item_type that was used to denote the type of group members during group creation.

omol

We've added ability to specify custom subaccount for realm users. It can be done in newly added home property in REST API requests or in Token home field in user management window.

omol

We've added support of the following templates in realm/user token parameters ACL topics:

realm.home.subaccount_id
realm.home.limit_id
user.subaccount_id
user.home.subaccount_id
user.home.limit_id

adsa

We've made significant improvements to the grants concept. Previously, each grant was associated with a single subaccount, requiring you to create multiple grants for multiple subaccounts. Now, you can create a single grant and assign multiple subaccounts to it. Consequently, the grant property gid is deprecated and will be removed on August 8th.

HTTP Methods: POST, DELETE, GET

Endpoint: platform/grants/{grant-selector}/subaccounts/{subaccounts}

Additionally, we have added the ability to disable or enable a grant:

HTTP Method: PUT

Endpoint: platform/grants/{grant-selector}

Request body:

{
  "enabled": false
}

omol

We've added new REST API method POST /realms/{realm-selector}/users/{user-selector}/login. Using this method realm owner can login as a user and obtain user's token with no knowledge of user's password and no access to user's linked identity provider accounts.

adsa

We have improved the responsiveness of the logging subsystem for platform items such as tokens, grants, and similar entities. Previously, these logs were stored together with REST API logs, which meant that searching for specific grant logs required sifting through a large volume of unrelated log messages. The key goal of this update was to separate the logs of different items into distinct storage locations, significantly reducing response times. Now, platform logs contain REST API logs and customer logs by default. If you want to retrieve logs for other entities, you need to specify which entity, for example:
```
curl -X GET 'https://flespi.io/platform/customer/logs'
{
 "item_type": 33,
 "count": 100,
 "reverse": true
}
```
Additionally, we've added support for all platform entities in the recycle bin. Newly created and later deleted items will now appear in the recycle bin. In the coming days, we will update the recycle bin to work with existing items as well.
You can now restore deleted geofences from the recycle bin.

adsa

We’ve introduced a limit per URI component. For example, requests with a component length exceeding 64KB will be rejected with a 414 URI Too Long error code.

A URI consists of components separated by /. For example, the request:

GET /gw/devices/all

consists of three components:

gw
devices
all

omol

We've added support of specifying web origins from which flespi tokens are allowed to be used.

Note: allowed origins validation works only for the requests performed in the web browsers. Requests sent from backend applications aren't affected by this validation.

You can set allowed origins in token origins field via API:

or in Allowed origins field via flespi panel:

Wildcard characters * and ? are supported in custom origins. Asterisk * matches to the interdomain dot-character . as well.

It is strongly recommended always to allow access to the flespi origins for your tokens unless you want to block access to the flespi panel and all the flespi public projects. In order to allow flespi origins you need to add
{"preset":"flespi"} object as one of the origins via API or select all flespi origins via flespi panel (see the screenshots above).

omol

omol
We've added support of allowed web origins and allowed IPs in token parameters for realms and users.

adsa

We've introduced support for new user-defined headers to enhance traceability between REST API requests and their corresponding actions.

x-flespi-app: Can include the name of the application making the request. It will be stored as the app parameter.
x-flespi-trace: Can contain a unique identifier for the request. If omitted, flespi will generate one automatically. It will be stored as the trace parameter.

REST API request:

Device action:

adsa

We've extended PATCH REST API methods to all entity types in the flespi platform(previously limited to select entity types). This enhancement allows for partial updates to entity fields, making it easier to modify specific fields without affecting others.

Use Cases:

Update metadata without retrieving and resubmitting the entire object
Modify specific configuration parameters without affecting others

omol

We've added role entity for the realms. It is designed to aggregate users' token rules management and share common practices (such as complex ACLs) between different users.

Each realm now has default role, which contains Users' home (home in REST API) and Default users' token parameters (token_params in REST API) attributes, previously stored as root attributes of the realm object.

Each custom role is based either on the realm default role, or on the another custom role, based on the realm default role. Each user also may have its own role, if the realm default role does not suit the needs. Only user role defines the final token rules (home and token_params) which are applied to the user's token. User role can be based either on the realm default role or on the custom role.

It is possible to override Token home (home in REST API) and Token parameters (token_params in REST API) attributes for custom and user roles. If those parameters are not defined, then their values are obtained from the corresponding values of the base role.

All old REST API requests (realms and users management without roles) continue working fine, but soon will be marked as deprecated.

In order to migrate to the new REST API you need to modify requests which work with the realms and users.

For the realms you need to move home and token_params values into the new role object. For example, the following JSON value

{
  "name": "realm1",
  "home": {
    "type": 0
  },
  "token_params": {
    "access": {
      "type": 0
    },
    "ttl": 1
  }
}

starts looking like this

{
  "name": "realm1",
  "role": {
    "home": {
      "type": 0
    },
    "token_params": {
      "access": {
        "type": 0
      },
      "ttl": 1
    }
  }
}

For the users you need to move home and token_params values into the new role object with additional property type of the string value inherit.default. For example, the following JSON value

{
  "name": "user1",
  "home": null,
  "token_params": {
    "access": {
      "type": 0
    },
    "ttl": 1
  }
}

starts looking like this

{
  "name": "user1",
  "role": {
    "type": "inherit.default",
    "home": null,
    "token_params": {
      "access": {
        "type": 0
      },
      "ttl": 1
    }
  }
}

adsa

Grants: Own Account Access Control

New Feature: Grants can now provide access to the current account itself, enabling flexible permission management within a single account hierarchy level.

What's New

Added "Own account" (platform/customer with own CID) as a grantable entity type. This allows creating grants that control access to the account where the grant is created, rather than only to child subaccounts or specific items.

Access Levels

Default (read-only):

View account details and gateway items (channels, devices, etc.)
Does not include access to platform entity logs or sensitive data

Additional access levels:

create-devices - Allow device creation in the granted account
create-channels - Allow channel creation in the granted account
create-calcs - Allow calculator creation in the granted account
create-plugins - Allow plugin creation in the granted account
create-streams - Allow stream creation in the granted account
create-modems - Allow modem creation in the granted account
create-groups - Allow group creation in the granted account
create-geofences - Allow geofence creation in the granted account
create-containers - Allow container creation in the granted account
create-cdns - Allow CDN creation in the granted account
create-assets - Allow asset creation in the granted account

Full access:

operate-as - Complete control over the account, equivalent to master token access