Trust anchor delivery¶

When a device is activated, trustmint delivers the platform trust anchor — the intermediate CA certificate a device must trust to validate its own leaf and the broker it connects to. If you implement a factory provision-role backend, this page is the wire contract for receiving that anchor and writing it into the device trust store.

The anchor is delivered as a signed envelope on the activation call to your backend. It is also re-delivered on every re-activation, so a device that lost its trust store during a deactivation window recovers automatically.

Envelope¶

{
  "trust_anchor": {
    "pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
    "fingerprint_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
  }
}

Field	Type	Meaning
`pem`	string	The intermediate CA certificate as a PEM block (~2–4 KB). Write it verbatim into the device trust store — do not re-encode or re-order.
`fingerprint_sha256`	string	Lowercase hex SHA-256 over the DER of the certificate. The stable idempotency handle (see below).

The envelope is the payload of the activation request to your backend and is signed with your registrar’s FGAI-HMAC access-key / secret-key pair (see Registration). Verify the signature against your registered key before trusting the body.

When it is delivered¶

Activation	Trust anchor included?
First activation	Yes
Re-activation (from a deactivated device)	Yes — re-delivered so a device that lost its store recovers

Every activation ships the current anchor. If the platform CA rotates, the next activation carries the new generation — there is no stale cache to invalidate.

Idempotency¶

Deduplicate on fingerprint_sha256: if the device trust store already contains a certificate with the same fingerprint, the write is a no-op. This keeps re-activations and any future over-the-air rotation delivery from creating duplicate trust-store entries. Use the fingerprint — not the PEM bytes — as the dedup key.

Requests also carry an Idempotency-Key header at the request boundary; re-sending the same key for the same device+activation returns the existing result rather than re-fetching a certificate.

Errors¶

Trust-anchor failures surface as problem responses with these codes:

Code	Meaning
`THM-TRUST-ANCHOR-UNAVAILABLE`	The platform CA certificate could not be fetched at delivery time. Retry with backoff.
`THM-TRUST-ANCHOR-MALFORMED`	The fetched anchor failed validation before delivery. A platform-side incident — do not retry blindly.
`THM-TRUST-ANCHOR-DELIVERY-FAILED`	The activation could not complete anchor delivery; the device stays in its prior state. Safe to retry the activation.

An activation that cannot deliver the anchor rolls the device back to its source state — a deactivated device stays deactivated rather than half-activated without a valid trust store.