Backend Integration

The Eixam Flutter SDK relies on a partner backend to provide signed sessions and support key operational endpoints.

What the partner backend must provide

1. A signed SDK session (appId, externalUserId, userHash)
2. Canonical identity support via GET /v1/sdk/me
3. MQTT operational support for SOS and telemetry
4. Transactional HTTP support for SOS cancel
5. Contacts and backend device registry surfaces

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:

final sdk = await EixamConnectSdk.bootstrap(
  const EixamBootstrapConfig(
    appId: 'partner-app',
    environment: EixamEnvironment.production,
    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 and contacts	HTTP

Authentication

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.

Device identity in payloads

• Telemetry and SOS payloads may include deviceId matching the paired device's hardware_id
• The canonical hardware_id is the Meshtastic/node identifier (e.g., CF:82...), not the local BLE transport ID or the friendly BLE name (e.g., Meshtastic_1aa8)
• If no paired hardware ID is available, deviceId may be omitted

note

The SDK does not call partner auth or signing routes, and does not compute the signature locally.

Realtime transport

The public field names mqttUrl / websocketUrl are stable. The actual broker URI may use ssl://, tls://, tcp://, ws://, or wss:// depending on environment and transport client.