API & SDK

API reference

The TrustFix REST API — org-scoped API-key auth, the public verification endpoints, and the route groups documented in the OpenAPI spec.

TrustFix exposes a REST API for the same surfaces you use in the product: connector lifecycle, findings, remediation, evidence, the Trust Ledger, and the public verification endpoints. The canonical contract is the OpenAPI specification at docs-site/openapi.yaml, which CI keeps at 100% coverage of the public routes.

Authentication

There are two ways to authenticate, declared in the spec's security schemes:

• Org API key (for integrations). Mint a key from the Admin Portal API Keys section. The plaintext token (tfx_live_… / tfx_test_…) is shown exactly once and only its SHA-256 hash is stored. Send it as a Bearer token:

  curl https://trustfix.dev/api/findings \
    -H "Authorization: Bearer tfx_live_..."
  

  Keys are least-privilege and scoped — available scopes include findings:read / findings:write, fixes:read / fixes:write, ledger:read, and webhooks:read / webhooks:write. Manage keys at POST /api/org/api-keys, list metadata (never the secret) at GET /api/org/api-keys, and revoke at DELETE /api/org/api-keys/[id].

• First-party session cookie (browser). The product UI authenticates with the __Host- prefixed TFID session cookie, issued on sign-in plus MFA. Session-cookie auth is browser-only and out of scope for the SDK.

Webhook deliveries are verified with an HMAC signature header rather than an API key. Every org-scoped endpoint is tenant-scoped and rate-limited, and an empty estate returns honest empty results rather than fabricated data.

Public verification endpoints

A small set of GET-by-id verifiers are public — the org is derived from the unguessable id, so no API key is needed:

• GET /api/agent-passport/[id] — verify an agent passport.
• GET /api/trust-receipt/[id] — verify a signed posture snapshot (Trust Receipt).
• GET /api/ledger/[id]/proof — a Merkle inclusion proof for a ledger entry (org-scoped).

These return a genuine cryptographic verdict — a tampered artifact verifies as false. Issuing and revoking the underlying artifacts is authenticated and org-scoped.

Route groups

The spec organizes the surface into tagged groups. The main ones are:

The full request and response shapes live in docs-site/openapi.yaml. For a typed client, see the SDK.