Backend Integration

The Eixam Flutter SDK relies on the partner backend for identity signing and on Eixam Platform endpoints for SDK operations. Keep those responsibilities separate.

What the partner backend must provide

1. Authenticate the user in the partner product.
2. Map that user to a stable externalUserId.
3. Generate or obtain a signed SDK session (appId, externalUserId, userHash) without exposing the app secret.
4. Return the signed session to the authorized mobile app over the partner's authenticated channel.

The Eixam Platform, not the partner mobile app, provides canonical SDK identity, devices, firmware, country configuration, SOS, telemetry, contacts, and realtime operational endpoints.

Signing flow

The partner backend owns the app secret and signs the user identity. The signing step must happen on the server — never in the mobile client.

Step	Actor
Store the app secret	Partner backend
Generate userHash for appId + externalUserId	Partner backend
Send the signed session to the mobile app	Partner backend
Bootstrap with the signed session	Mobile app
Reuse identity for HTTP and MQTT	SDK

See Identity Signing (JS) for server-side implementation examples.

Signed session contract

Minimum fields:

const EixamSession.signed(
  appId: 'partner-app',
  externalUserId: 'partner-user-123',
  userHash: 'signed-session-hash',
)

Bootstrap and session

If the app already has a signed session at startup, pass it as initialSession. The snippet assumes notificationTexts is a non-empty EixamNotificationTexts value from the host app:

final sdk = await EixamConnectSdk.bootstrap(
  EixamBootstrapConfig(
    appId: 'partner-app',
    environment: EixamEnvironment.production,
    notificationTexts: notificationTexts,
    initialSession: EixamSession.signed(
      appId: 'partner-app',
      externalUserId: 'partner-user-123',
      userHash: 'signed-session-hash',
    ),
  ),
);

If not available at startup, bootstrap without a session and call setSession(...) later.

Operational endpoints

Operation	Transport
Session enrichment	GET /v1/sdk/me
SOS trigger	Operational (MQTT)
SOS cancel	POST /v1/sdk/sos/cancel
Active SOS rehydration	GET /v1/sdk/sos
Telemetry	Operational (MQTT)
Devices	HTTP (registry / pairing flows as documented)
Emergency contacts	HTTP — /v1/sdk/contacts
Firmware availability/artifact preparation	HTTP, called by the SDK-owned OTA flow
Country resolution and device config	HTTP, called by the SDK-owned LoRa radio-region flow
SDK user erasure	DELETE /v1/sdk/me, called by deleteUserData(...)

Host UI should not call firmware artifact, reverse-geocoding, or country-config routes directly. The SDK combines them with BLE state, safety gates, user confirmation, and verification.

Auth

HTTP

X-App-ID: <appId>
X-User-ID: <externalUserId>
Authorization: Bearer <userHash>

MQTT (broker-native, no Bearer prefix)

username: sdk:<appId>:<externalUserId>
password: <userHash>

MQTT uses clean sessions. The same signed identity is shared across HTTP and MQTT.

Feedback authentication

submitAppFeedback(...) is different: it requires the current authenticated Eixam user JWT. SDK HMAC headers alone do not authorize that route.