Authentication

Key format

fmk_<tier>_<prefix12>_<secret32>

• tier ∈ free | pro | enterprise.
• prefix12 is 12 hex chars stored in plaintext in the API DB for O(1) lookup.
• secret32 is 32 hex chars. Never stored: only its argon2id hash hits disk. The full key is shown exactly once at creation.

Send it as a Bearer token:

Authorization: Bearer fmk_pro_abc123def456_<32hex>

Tiers

Tier	On-chain attestations / month	Off-chain	Rate limit
free	20	unlimited	30/min
pro	2 000	unlimited	600/min
enterprise	unlimited	unlimited	6 000/min

Off-chain attestations are unmetered at every tier. Rate limits are sliding-window per key. Anonymous (unauthenticated) requests fall back to a 30/min per-IP bucket.

When you hit the monthly quota, write endpoints return 429 QUOTA_EXCEEDED with the reset timestamp:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly onchain attestation quota exhausted for tier free.",
  "details": {
    "tier": "free",
    "kind": "onchain",
    "used": 20,
    "limit": 20,
    "resetsAt": 1717200000000
  }
}

Rotating keys

Manage keys from your account dashboard. Revoking a key is permanent (it’s marked revoked_at and can’t be re-enabled). Mint a new one if you need to rotate.

Public vs gated endpoints

• Public (no auth): GET /healthz, GET /readyz, GET /openapi.json, GET /v1/attestations/:uid, GET /v1/attestations?hash=.... The badge endpoint at https://verify.fidemark.dev/api/attestation/:uid is also public; it lives on the verify web app, not the Enterprise API.
• Gated: every POST endpoint and GET /v1/audit/export and GET /v1/webhooks.