Realtime

Realtime is an optional Cloud infrastructure service backed by Centrifugo. Operators must configure and deploy it before token issuance succeeds. The first rollout serves authenticated project owners in the Cloud console. Inventory and Parcels views automatically refresh on notifications. AI lifecycle events share the same delivery foundation; AI token/audio streams continue using their existing transports.

Project and tenant boundaries

Each subscription belongs to one project, one module, and one tenant scope. Omit tenantId for an owner-authorized aggregate channel across the project; pass 0 for only the default tenant, or a positive numeric tenant ID for that tenant. Cloud checks membership, owner role, product enablement and tenant ownership/status each time it issues or refreshes a token.

Tokens expire after 60 seconds. Access changes take effect on refresh/expiry. Immediate proactive disconnect is not part of this initial rollout. Non-owner subscriptions, presence and customer publishing are not enabled.

Console token contract

The management endpoint accepts your console authentication token; it does not accept fc_live_ project keys.

POST /api/v1/projects/123/realtime/tokens
Authorization: Bearer <console-access-token>
Content-Type: application/json

{"module":"inventory","tenantId":12}

The response contains websocketUrl, channel, connectionToken, subscriptionToken and expiresAt under data. Keep tokens in memory and obtain fresh tokens through authenticated management requests. Never include a long-lived Cloud API key in a WebSocket URL. The SDK connection and subscription token callbacks must both refresh their token.

Notices and recovery

Publications contain only an invalidation notice:

{"id":"evt_example","type":"inventory.stock.changed","createdAt":"2026-10-12T00:00:00Z","action":"invalidate"}

Fetch current state through the module API after receiving a notice. History does not contain stock movements, addresses, prompts, generated results or billing evidence. Delivery is at least once: deduplicate event IDs, coalesce repeated refreshes, and fetch current state on reconnect. Ordering is not guaranteed; never use notices as authoritative stock deltas or payment instructions.

The initial history window is at most 100 notices per channel and 60 seconds. Recovering notices helps brief disconnections; API refresh remains necessary after any reconnect. Delivered ingestion receipts are retained for seven days, after which an old retried event may be delivered again.

Webhooks and background work

Webhooks remain the server-to-server callback interface with signatures and retries. Inventory events commit in its own database transaction and relay asynchronously. Realtime fanout and webhook deliveries are persisted together by the control plane. Realtime outages retain pending work and do not authorize or undo financial/stock mutations.

Customer-defined durable pub/sub, billing and Geo event producers, fine-grained member subscriptions and commercial cluster-wide connection quotas are subsequent work.