SDK quickstart — Go + Python

trustmint ships client SDKs in two languages so integrators on either stack write less integration code. The SDKs handle the FGAI-HMAC AK/SK signing (the part that is NOT AWS SigV4 — see registration) and a generated typed-error surface. This page is a front door; the SDK source + READMEs are the authoritative reference.

These are the backend-integration SDKs (your factory-service ↔ thingmake). The device-side SDKs that implement the on-device DDI-1 wire contract live in a separate repo, SiriusVoyager/ddi — the old trustmint terminals/ tree was removed. Don’t look for device SDKs here.

Source of truth

Artifact

What it is

sdks/README.md

Top-level SDK guide — first 5 minutes, AK/SK wire scheme, example matrix, Makefile targets

sdks/go/

Go SDK (generated client + signing/ transport)

sdks/python/

Python SDK (generated client + auth/ signers)

sdks/examples/

Eight runnable example programs (four scenarios × two languages); model-registry examples are a Phase 7.18 follow-up

sdks/examples/_stack/

A throwaway local test harness (Keycloak + Postgres + a thingmake) the examples run against — a disposable test fixture, not a deployment path

The SDKs are generated from the OpenAPI snapshot services/thingmake/docs/openapi/thingmake-openapi.{json,yaml} (rendered on the API reference page) and the error catalog thingmake-error-catalog.json — do not hand-fork them.

First 5 minutes

# 1. Bring up the throwaway example harness (Keycloak + Postgres + thingmake).
#    This is a disposable local test fixture for the examples — NOT a deploy path.
#    Real dev runs on the dev lane (LocalStack k3d, *.fgai.test); real integration
#    targets api.flexgalaxy.ai.
make -C services/thingmake/sdks example-stack-up

# 2. Pick a language and read the per-SDK README:
#    services/thingmake/sdks/go/README.md   or   .../python/README.md

# 3. Or run the whole demo in one shot:
cd services/thingmake/sdks
make sdk-smoke      # ~3 min: harness up + all 8 examples + harness down

make sdk-smoke is the one-shot demo — it brings the harness up, runs all eight example programs, and tears the harness down in a single managed lifecycle (CI uses exactly this target). For a single language, use make sdk-smoke-go or make sdk-smoke-python.

The example matrix

#

Scenario

Auth

Go

Python

01

Register a factory-service (capture one-time AK/SK)

JWT

sdks/go/examples/01-register-factory-service/

sdks/python/examples/01-register-factory-service/

02

Receive a state-change notification (subscription + webhook listener)

AK/SK

sdks/go/examples/02-receive-state-notification/

sdks/python/examples/02-receive-state-notification/

03

Poll state changes via cursor (GET /api/v1/state-changes?since=…)

AK/SK

sdks/go/examples/03-poll-state-changes/

sdks/python/examples/03-poll-state-changes/

04

Verify a webhook signature (host the receiver + call the verify helper)

webhook secret

sdks/go/examples/04-verify-webhook/

sdks/python/examples/04-verify-webhook/

Example 01 mints a JWT against the in-harness Keycloak, calls POST /api/v1/factory-services, and writes the one-time {access_key_id, secret_access_key} to a git-ignored .aksk.env. Examples 02 / 03 / 04 read .aksk.env for credentials. Never commit .aksk.env — it holds your secret-key.

Generated client surface

The generated Go/Python clients are regenerated from the OpenAPI snapshot and now include the current device-model registry endpoints:

  • /api/v1/thingmake/vendors

  • /api/v1/thingmake/models

  • /api/v1/thingmake/models/{id}/share

  • /api/v1/thingmake/models/import

  • /api/v1/thingmake/software

  • /api/v1/thingmake/models/{id}/software

Treat this as an SDK-availability statement, not an endorsement of the entire legacy API surface. Several exported routes predate the current model-registry and DDI architecture. Phase 7.18 records the cleanup rule: examples and gates should bless only the surfaces they exercise, and stale exported APIs must be removed or explicitly quarantined before they are promoted as public contracts.

What next