Getting started

This is the zero-to-registered journey: four linear steps that take a brand-new integrator from nothing to a factory-service backend that registers, self-certifies, receives notifications, and polls state-changes. Each step links the relevant SDK example and the error catalog entry you will hit if something is wrong.

Prerequisite — pick a target

trustmint is env-less: environments are roles, not accounts.

  • dev lane (inner loop). A LocalStack + k3d stack served under *.fgai.test. This is where you iterate before you ever touch a live color. The thing services run on k3d; every managed dependency (Postgres/RDS, MSK, Redis, S3, ECR, Route53, Secrets Manager) is the LocalStack-emulated service.

  • live. The public service/API edge is api.flexgalaxy.ai (KrakenD). Current browser apps are reached through the DotID account console at console.flexgalaxy.ai, not the deprecated pre-shell TrustMint gateway.

The backend services listen on port 8080. The current thingmake release is v2.11.

On the SDK example harness. The SDK repo ships a throwaway local test harness (Keycloak + Postgres + a thingmake) purely so the eight example programs have something to talk to. It is a disposable test fixture, not a deployment path — real dev happens on the dev lane above, and real integration targets api.flexgalaxy.ai. See SDK quickstart.

Step 1 — register a factory-service

Mint a registrar JWT and POST /api/v1/factory-services to capture your one-time <your-access-key-id> / <your-secret-key>. Full walkthrough: Registration.

  • SDK example: 01-register-factory-service (Go + Python) does exactly this and writes the pair to a git-ignored .aksk.env.

  • If it fails: this endpoint is JWT-gated, so failures are foundation-auth codes — bucket 1 of the error catalog (THM-10100 JWT expired, THM-10110 JWT signature invalid, THM-10120 JWT missing). The AK/SK signing codes (bucket 2, THM-201xx) apply to the signed requests in later steps, not to this registrar-JWT call — see Registration for the full split.

Step 2 — run the conformance suite against your backend

Self-certify your backend implements the contract correctly before you wire it into anything. Point your backend’s thingmake-base-url at the suite’s --listen-addr (default :8910), then run the single command. Full walkthrough: Conformance.

thingmake-conformance \
  --backend-url http://your-factory-backend:8080 \
  --access-key   <your-access-key-id> \
  --secret-key   <your-secret-key>

  • Reference: conformance/services/thingmake/README.md — exit 0 means every scenario passed.

  • If it fails: registrar-lifecycle + thing-state-machine codes — buckets 3 and 4 of the error catalog (THM-30xxx, THM-40110 illegal transition, THM-40120 missing Idempotency-Key). The suite names the expected THM-NNNNN in each failure diagnostic.

Step 3 — receive a thing-state notification

Subscribe to notifications and host an HMAC-verifying receiver so a state-change is pushed to you. Full walkthrough: Webhooks.

  • SDK example: 02-receive-state-notification (subscription + listener) and 04-verify-webhook (HMAC verify helper).

  • Remember: acknowledge_polling_still_mandatory=true is required — a subscription does not replace polling.

  • If it fails: subscriptions codes — bucket 6 of the error catalog (THM-60110 polling not acknowledged, THM-60120 non-https target_url, THM-60140 invalid event_filter).

Step 4 — poll the state-changes feed

Webhooks are best-effort; the durable backstop is the cursor-paged feed. Poll GET /api/v1/state-changes?since=<next_cursor> and persist next_cursor between calls. See the state-changes group in the API reference.

  • SDK example: 03-poll-state-changes (cursor loop).

  • If it fails: state-changes-feed codes — bucket 5 of the error catalog. Most importantly THM-50120 — a cursor older than 72h returns HTTP 410 and you must full-sync via GET /api/v1/things, then resume polling. Also THM-50100 (drop ?registrar_id=) and THM-50110 (malformed cursor).

What next

You now have a backend that registers, certifies, subscribes, and polls. From here: