Integrating with trustmint

This is the developer / integrator documentation for trustmint — the device-trust, registry, telemetry, and factory tier of the FlexGalaxy.AI APaaS platform. It is the front door for engineers who integrate against trustmint: firmware and backend engineers at a factory (Syrius Robotics and future partners), platform integrators wiring device fleets onto FlexGalaxy.AI, and anyone building against trustmint’s REST/gRPC surfaces.

What trustmint is. trustmint onboards physical devices (things) onto the platform, mints their trust anchors and identity certificates, drives them through a five-state lifecycle, and reports every state change to your backend. Eight Go and Python backend services sit behind the api.flexgalaxy.ai KrakenD edge gateway; device firmware speaks the DDI-1 wire contract (HTTPS 443 mTLS + MQTT 8883) directly.

Environments (env-less; environments are roles).

Role	Where	Host
dev	LocalStack + k3d inner loop	*.fgai.test
staging	idle color	api.flexgalaxy.ai for public APIs; browser apps launch from console.flexgalaxy.ai when registered in the app shell
prod	active color	api.flexgalaxy.ai for public APIs; browser apps launch from console.flexgalaxy.ai

The public API edge for both staging and prod is api.flexgalaxy.ai (KrakenD). There are no per-environment AWS accounts — staging and prod are the idle and active blue/green colors on the colored EKS clusters (blue-eks / green-eks, namespace trustmint). The deprecated pre-shell TrustMint frontend gateway is not the browser entry point for current Thing* apps.

Auth in one paragraph. trustmint delegates all authorization decisions to DotID’s policy-engine (Policy Decision Point; see ADR-0004). Users reach the consoles via Keycloak SSO. Factory services authenticate machine-to-machine with an access-key / secret-key pair using the canonical FGAI-HMAC signing scheme (FGAI4 derived key — not AWS SigV4); thingmake verifies signatures through the DotID /v1/internal/verify-signature RPC. See Registration.

Where to start

• Never touched trustmint? → Getting started walks you zero-to-registered in one hour.

• Need credentials? → Registration mints an AK/SK pair and explains FGAI-HMAC signing.

• Wiring the HTTP surface? → API reference renders the generated thingmake OpenAPI (four endpoint groups).

• Firmware engineer? → DDI-1 contract is the canonical device wire contract.

Contents

Integrating with trustmint

• Getting started
  • Prerequisite — pick a target
  • Step 1 — register a factory-service
  • Step 2 — run the conformance suite against your backend
  • Step 3 — receive a thing-state notification
  • Step 4 — poll the state-changes feed
  • What next
• Registration — get an access-key / secret-key
  • Step 1 — register the factory-service (JWT-gated)
  • Step 2 — sign every later request (FGAI-HMAC-SHA256)
  • When signing fails
  • What next
• API reference
  • The four factory endpoint groups
  • Download the raw spec
  • Rendered reference
• Thing lifecycle — five states
  • The five states
  • State transitions at a glance
  • Where errors map to states
  • Trust anchors ride the ACTIVATE edge
• Webhooks — subscribe to thing-state notifications
  • Step 1 — create the subscription (AK/SK-signed)
  • Step 2 — verify the HMAC on every delivered event
  • Step 3 — keep polling GET /api/v1/state-changes
  • What next
• Error catalog
  • Source of truth (do not hand-edit)
  • The THM-NNNNN code scheme
  • How the SDKs use it
• SDK quickstart — Go + Python
  • Source of truth
  • First 5 minutes
  • The example matrix
  • Generated client surface
  • What next
• Conformance suite
  • Source of truth
  • Single-command invocation
  • Prerequisite — point your backend at --listen-addr
  • Exit codes
  • Scenario coverage
  • What next
• Roles and access control
  • Roles
  • Permission-boundary model
  • IAM separation
  • Authorization is delegated to DotID’s Policy Decision Point
  • Tenant and platform tools
  • Tool summary

Protocol & trust

• DDI-1 Contract — Device Direct Interface v1
  • Change control
  • Why this stub exists
• Trust Anchor Delivery — Activation Saga Payload Contract
  • 1. Wire envelope (D-04)
  • 2. When the envelope is delivered (D-02, D-10, D-11)
  • 3. Freshness guarantee (D-07)
  • 4. Idempotency
  • 5. Failure semantics (D-12, D-13)
  • 6. Rotation cascade reference (bazaar #5)
  • 7. Out of scope for v2.10
  • Change log
• Device MQTT topic access
  • Your own device subtree
  • Scope topics (subscribe-only)
  • Per-device isolation
  • Access follows your scope membership
  • Default-deny

Concepts & design

• Thing Access Model
  • Core concepts
  • Enrollment vs Access
  • Lifecycle
  • Data model
  • API endpoints
  • Examples
• Device Models and Artifact Applicability
  • A model has its own identity
  • Artifact Applicability Is Descriptor Metadata
  • Provisioning by model
  • Sharing a model to another factory
• Device attributes
  • The three buckets
  • CLIENT — report facts up
  • SHARED — receive config, acknowledge it
  • Wire topics
  • Python SDK
• Data model
  • Service split at a glance
  • ThingHub — the thing registry
  • ThingIO — telemetry, scopes, pipelines
  • ThingLab — device simulation (api-only)
• Registrar, ThingMake & Arsenal — Design Document
  • Overview
  • Data model
  • Application architecture
  • API design
  • Access control summary
  • Migration strategy

Decisions & meta

• Architecture Decision Records
• Contributing to these docs
• Documentation License