[Changelog] flespi platform API

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

adsa

We added a new POST /logs/calculate method for all entity types that have dedicated logs — devices, channels, streams, calculators, webhooks, groups, modems, subaccounts, CDNs, grants, MQTT broker, and customer.

This method brings the power of flespi analytics to entity logs. You can now define selectors and counters — the same way you do in calculators — but applied to log entries instead of device messages. This enables on-demand aggregation and statistics extraction from logs at scale, without the need to fetch all log entries and process them manually.

Practical use cases include:

Connection statistics: calculate daily connection count, total duration, and traffic per device from device logs
Error analysis: aggregate error events by type and frequency across channels or streams
Command audit: build intervals of command execution activity per device
Group membership tracking: extract intervals when devices were added/removed from groups using event codes 801/802

Example — calculate daily connection count and total traffic for a device:

POST /gw/devices/{dev-selector}/logs/calculate

{
  "selectors": [
    { "type": "datetime", "split": "day" }
  ],
  "counters": [
    {
      "type": "expression",
      "name": "connections",
      "expression": "$event_code == 300",
      "method": "summary"
    },
    {
      "type": "expression",
      "name": "bytes_received",
      "expression": "$recv",
      "method": "summary"
    }
  ],
  "from": 1706745600,
  "to": 1707350400,
  "timezone": "UTC"
}

The request body schema is identical to what you already use in calculators, so the learning curve is minimal. All selector types (expression, datetime, geofence, inactive) and all counter types (expression, parameter, message, dataset, etc.) are supported.

shal

We are deprecating next AI-related methods which will be removed in April:

POST /customer/generate/pvm-code — PVM code generator. Use POST /ai/tools/generate-pvm-code instead.
POST /gw/channels/protocols/.../device-types/.../assistance and GET /gw/channels/protocols/.../device-types/.../knowledge — device documentation access. Use POST /ai/tools/search-device-documentation instead.

Please use modern flespi API for AI services instead.

omol

We've updated realms API so that it's possible to change role type and role parent ID if effective token home account policy is not affected by this change (e.g. when new parent role home matches to the old one).

omol

Deprecation notice: realm/user home and token_params must move into role object, update by May 21st

When creating or updating realms and realm users, passing home and token_params as top-level fields is now deprecated. Use the role object instead.

Before (deprecated):

PUT /platform/realms/{id}/users/{id}
{"token_params": {"ttl": 60, "access": {"type": 0}}}

After (recommended):

PUT /platform/realms/{id}/users/{id}
{"role": {"type": "inherit.default", "token_params": {"ttl": 60, "access": {"type": 0}}}}

The same applies to realm creation and updates - wrap home and token_params inside the role object.

Requests using the old format will continue to work but now return a deprecation warning in the response.

Affected endpoints:

POST/PUT/PATCH /platform/realms
POST/PUT/PATCH /platform/realms/{realm-id}/users

Support for the old format will be removed on May 21st, 2026.

omol

Realms and realm users can now be disabled

We added enabled flags for both realms and realm users.

What changed

Realms now have an enabled boolean field.
Realm users now have an enabled boolean field.
The default value is true for newly created realms and users.
Existing realms and users also get enabled: true.

Disabled users

When a realm user has enabled: false:

the user cannot log in;
any existing user token is revoked.

Disabled realms

When a realm has enabled: false:

all public realm API endpoints are blocked except GET /realm/{public_id}/info;
existing tokens of realm users are revoked.

omol

Removed deprecated API: realm/user home and token_params top-level fields

The realm and realm-user API now requires role-related configuration to be passed inside the role object.

Use role.home for home access configuration and role.token_params for token settings.

Affected endpoints:

POST/PUT/PATCH /platform/realms
POST/PUT/PATCH /platform/realms/{id}/users

adsa

Subaccount deletion now returns 409 Conflict if the target subaccount still has REST operations in flight (long-running device commands, ongoing analytics, etc.).

Retry the DELETE after the in-flight requests on that subaccount complete. Once the subaccount is idle, deletion proceeds normally.

shal

flespi system changelogs delivered via MQTT and REST

Each flespi system — telematics hub, MQTT broker, storage, platform, and AI — now maintains its own changelog feed aggregating new posts from the forum changelog topics of the system and its applications: the telematics hub feed also carries analytics, tachograph, Toolbox, TrackIt, MapView, SetBox, and Tacho Bridge App updates; the MQTT broker feed carries MQTT Tiles and MQTT Board; the platform feed carries the flespi panel.

Realtime: subscribe to flespi/message/{gw|storage|mqtt|platform|ai}/changelog MQTT topic of the systems you rely on.
History: GET /{gw|storage|mqtt|platform|ai}/changelog-posts returns the full accumulated history, e.g. the latest platform post: GET /platform/changelog-posts?data={"reverse":true,"count":1}

Each post carries the title, url, and author of the original forum post, its text in markdown, the publication timestamp, and the name of the specific changelog it belongs to — the changelog section of each system's API documentation lists the names to expect.

Both the MQTT topics and the API are accessible with any token of the account, including ACL tokens, no extra permissions required. Same access provided and to flespi announcements topic flespi/message/platform/customer/announce to which you can subscribe for NOC messages and forward them into your monitoring system.

Announcements now reach subaccounts: platform announcements (noc, news) and the changelog feeds are delivered to all accounts including subaccounts — previously to top-level accounts only. If you forward these topics to external systems via webhooks or MQTT subscriptions configured per subaccount, filter by cid or keep the forwarding in a single account to avoid duplicate notifications.

shal

Two improvements in flespi expressions:

New in operator for string membership: configuration.ident in ('354017111111111', '868324022222222') - a compact and faster replacement for long chains of == comparisons joined by ||. Exact matching against constant strings, no wildcards. Especially handy in REST API selectors to address many devices by their idents.
Backslash escaping in string literals: \', \" and \\ now work inside strings, so values containing both quote types can be matched directly, e.g. key == "it's a \"quoted\" text". Note: '\\' now means a single backslash.

Available everywhere expressions are used - selectors, filters, calculators, plugins, webhooks, MQTT subscriptions.

adsa

The metadata field is now part of the default response for channels, devices, streams, calcs, plugins, groups, geofences, assets, modems, containers, CDNs, webhooks, subaccounts, grants, limits, tokens, AI agents and AI connectors — you no longer need to request it explicitly via ?fields=.

For geofences, the geometry field is now returned by default as well.

omol

OAuth server support for flespi realms and MCP clients

TL;DR

Realms can now authorize OAuth clients, including compatible MCP clients, without users sharing flespi tokens. Realm owners enable OAuth and allow specific clients using their CIMD URLs; users then sign in and approve access through the usual realm login flow.

For a quicker setup, the realm's Info tab provides integration buttons for Claude Code, Claude, Cursor, VS Code, LM Studio and Goose.

Details

We have added an OAuth 2.0 authorization server to flespi realms. Applications can now request access on behalf of a realm user instead of asking the user to create and share a flespi token. The user signs in with their realm credentials or configured identity provider, reviews the requested access, and explicitly approves or denies it. The resulting access remains limited by that user's realm token ACLs.

Realm OAuth currently supports public clients using the Authorization Code flow with mandatory PKCE (S256), refresh tokens, and the default scope. Only client identification through Client ID Metadata Documents (CIMD) is supported.

Getting access

OAuth server is disabled by default. A realm owner must:

Enable the realm's oauth_server setting.
Add the exact public HTTPS URL of the application's OAuth Client ID Metadata Document (CIMD) to oauth_server.allowed_clients.

The CIMD URL is also the OAuth client_id. Up to 16 clients can be allowed per realm.

OAuth server discovery

OAuth clients can discover the realm authorization server using its standard metadata URL:

https://flespi.io/.well-known/oauth-authorization-server/realm/<realm-public-id>/oauth

The server metadata is also available directly at:

https://flespi.io/realm/<realm-public-id>/oauth/authorization-server

MCP integration

OAuth-capable MCP clients that support CIMD can connect directly to either realm MCP endpoint:

https://flespi.io/realm/<realm-public-id>/ai/mcp/develop
https://flespi.io/realm/<realm-public-id>/ai/mcp/support

The MCP client must support OAuth protected-resource discovery, CIMD, HTTP redirects that preserve authorization and POST requests, and Streamable HTTP. SSE transport is not supported. Access to the develop and support MCP servers is governed by the realm user's existing ACLs rather than separate OAuth scopes.

adsa

Values in webhook log records are now truncated to 16 KB with a ...[truncated, N bytes] mark.

omol

We added new fields to improve tracing of requests authenticated through realms.

Request logs
REST API call logs may now include:

oauth_client_id - OAuth client that initiated the request
realm_id - associated realm ID
user_id - associated realm user ID

These fields are present only when applicable.

Tokens
Token responses now expose read-only realm_id and user_id fields. Both fields can also be used in token selectors.

adsa

Webhook chain: consistent response indexes

When a chained request is skipped by validate, it now leaves null in responses[] and response_codes[], so index N always points to the N-th request, as in the webhook logs. If your expressions compensate for the missing element, switch them to the request's position in the chain.

adsa

Blocked items now return 403

Requests rejected because an item is blocked return HTTP 403 instead of 400. The blocked code and reason in the error entry are unchanged. Update integrations that match on the 400 status.
Items blocked by a quantity limit are read-only: PUT, PATCH and assignment changes return 403. Reading and deleting still work, so you can delete items to lift the block.
Messages for streams and webhooks blocked by quantity, frequency or traffic limits are queued and delivered once the block is lifted, instead of being dropped.

« Previous Page