Runtime surface

This page separates two facts that must not be conflated:

  • SDK surface means a binding can encode, send, receive, or validate the operation.

  • Managed runtime means the public FlexGalaxy deployment currently routes and persists that operation end to end.

An SDK method is not evidence that its backend is live. The deployed gateway contract remains the authority if this summary and a tagged SDK release disagree.

Public HTTPS

Route

Authentication

SDK surface

Managed runtime

Purpose

POST /ddi/v1/identify

factory bootstrap bearer

Python, Android, C

live

resolve a registered model and serial; return an enrollment binding

POST /ddi/v1/provision

factory bootstrap bearer + enrollment binding

Python, Android, C

live

issue a certificate from an on-device CSR

GET /ddi/v1/time

none on the enrollment listener

Python, Android, C

live

gateway-local UTC fallback; standard HTTP Date is preferred

POST /ddi/v1/rotate

device mTLS

Python, Android, C

live

rotate the device certificate from a new CSR

/ddi/v1/ota/*

device mTLS

Python, Android, C

live when OTA is configured

certificate-bound HawkBit polling, downloads, and feedback

/ddi/v1/<thing_id> and /license/*

intended device mTLS + license token

Android compatibility API only

not published

legacy device status, request, and token-renewal shapes

/ddi/v1/bundles/*

device mTLS

none

reserved

resumable diagnostic bundle upload

/ddi/v1/commands/*/ack

device mTLS

none

reserved

HTTPS command acknowledgements

/ddi/v1/sentry-ingest/*

device mTLS

none

reserved

device error-ingest relay

HTTP/2 is the supported post-provision HTTPS transport. HTTP/3 and CoAP are not part of the current runtime.

MQTT 5

Devices connect directly to the shared EMQX listener at mqtts://things.flexgalaxy.ai:8883 with mTLS. ddi-gateway participates as a shared subscriber and down-channel publisher; it is not an HTTP proxy in front of the broker.

Topic

Direction

SDK surface

Managed runtime

device/<thing_id>/telemetry

device → platform

Python, Android, C

live; bridged to Kafka

device/<thing_id>/attribute/client

device → platform

Python, Android, C

live; bridged to ThingIO through Kafka

device/<thing_id>/attribute/shared/push

platform → device

Python, Android, C

live through the authenticated internal push plane

device/<thing_id>/commands

platform → device

Python, Android, C

live through the authenticated internal push plane

device/<thing_id>/attribute/shared/ack

device → platform

Python, Android, C

reserved; device publish is not yet persisted end to end

device/<thing_id>/commands/ack

device → platform

Python, Android, C

reserved; response delivery is not yet persisted end to end

device/<thing_id>/events

device → platform

Python, Android, C

reserved

device/<thing_id>/heartbeat

device → platform

Python, Android, C

reserved as a backend event; connection presence is observed locally

device/<thing_id>/logs

device → platform

none

reserved

The Android client also exposes desired/delta terminology inherited from an earlier twin abstraction. On the frozen wire contract those paths are the SHARED push and SHARED acknowledgement topics shown above. Use the attribute semantics, not the old name, when designing new applications.

SDKs must use the exact thing_id bound into the certificate SAN. The platform broker and gateway reject identity or topic substitution.

OTA behavior

The gateway derives the HawkBit controller identity from the verified device certificate, adds its server-held upstream credential, and rewrites HawkBit HAL and Location links back to https://things.flexgalaxy.ai/ddi/v1/ota. A device must not send a controller ID, HawkBit tenant, or GatewayToken.

The OTA proxy accepts GET, HEAD, POST, and PUT. It rejects path traversal, unverified device identity, unsupported methods, and incomplete server configuration.

Non-device interfaces

The following are not public DDI APIs:

  • POST /internal/v1/push-to-device is a cluster-internal, workload-JWT authenticated backend route.

  • /metrics and the operations health route are bound to an internal operations listener.

  • /ddi/v1/whoami is a diagnostic proof on the mTLS listener and returns gateway-internal material. SDKs and devices must not depend on it.

  • Bazaar, Dev2M, OTAForge, EntitleKit, and TrustMint management APIs do not route through DDI.