Getting started

This is the zero-to-registered journey: five 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 — one base URL, one credential

Everything trustmint exposes to you is reached over HTTPS at a single host:

Host

What it serves

https://api.flexgalaxy.ai

the trustmint capability API — the surface this guide uses

https://api.staging.flexgalaxy.ai

the same API, one release ahead, for integration testing

https://console.flexgalaxy.ai

the browser consoles, if you would rather click than call

Paths are capability paths, not service names: /provisioning/v1/… (registrars, enrollment, factory services, thing lifecycle, state changes), /access/v1/… (repositories, scopes, grants), /telemetry/v1, /twins/v1/…, /rules/v1/…, /pki/v1/…. The CLI reference lists every group, and the API reference renders the generated specification.

Two credential kinds exist, and you will use both in this guide:

  • an interactive bearer token from your account’s SSO login, used once to register your backend;

  • an access-key / secret-key pair issued by that registration, which signs every call afterwards with the FGAI-HMAC scheme (FGAI4 derived key — not AWS SigV4). See Registration.

Step 0 — Prove you can reach the API

Two endpoints under /pki/v1/ are public trust-anchor discovery and need no credential, so they are the cleanest first request: a 200 here proves DNS, TLS and routing before any signing question can confuse the diagnosis.

curl -fsS https://api.flexgalaxy.ai/pki/v1/jwks
curl -fsS https://api.flexgalaxy.ai/pki/v1/ca

The first returns a JWKS document — a keys array whose entries carry kty, alg and kid — used to verify signed artifacts such as the identity-blacklist snapshot. The second returns the PEM certificate chain your devices pin. If either fails, stop here: no later step can succeed. If they succeed, the platform is reachable and every remaining failure is about your credential or your payload.

Step 1 — Register a factory-service

Mint an interactive token for a registrar-admin identity, then POST /provisioning/v1/factory-services to capture your one-time <your-access-key-id> / <your-secret-key>. Full walkthrough: Registration.

curl -fsS -X POST https://api.flexgalaxy.ai/provisioning/v1/factory-services \
  -H "Authorization: Bearer <registrar-admin-token>" \
  -H 'Content-Type: application/json' \
  -d '{"registrar_id":"reg-acme-robotics",
       "model_id":"550e8400-e29b-41d4-a716-446655440000",
       "role":"identify",
       "endpoint_url":"https://factory.example.com/v1/identify"}'

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

  • The secret key is shown exactly once. No endpoint re-reads it; if you lose it, rotate the credential rather than re-registering.

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

Step 2 — Make your first signed call

Confirm the pair works before you build anything on it. Sign a read with FGAI-HMAC — the SDKs and the fgai CLI both do the signing for you. The CLI is published on dl.flexgalaxy.ai for macOS, Linux and Windows:

curl -fsSL https://dl.flexgalaxy.ai/fgai/install.sh | bash

fgai configure                       # stores the access key / secret key in a profile
fgai provisioning factory-services-list

A 200 with your own factory-service in the list means the credential, the signing scheme and the clock skew window are all correct. A THM-201xx means the signature did not verify — Registration documents the canonical string-to-sign.

Step 3 — Run the conformance suite against your backend

Self-certify that 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>

  • 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 4 — 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.

fgai provisioning state-change-subscriptions-create --body '{
  "target_url": "https://factory.example.com/hooks/thing-state",
  "acknowledge_polling_still_mandatory": true }'

  • 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 5 — Poll the state-changes feed

Webhooks are best-effort; the durable backstop is the cursor-paged feed. Poll GET /provisioning/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 /provisioning/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: