API keys

Inferio uses three classes of secrets. Knowing which one is which — and where each is safe to ship — is the first line of defence.

The three secret classes

There are no client-side tokens. Inferio is a server-to-server API by design — even the “test event” button in the dashboard is signed with the same whsec_* you use in production.

Generating keys

API tokens

1. Dashboard → Settings → API keys → Create token
2. Pick environment (test / live), name the token (e.g. production-server)
3. Copy the secret immediately — we store only a hash, so you’ll never see the plain value again

Webhook secrets

whsec_* secrets are generated automatically when you create a webhook endpoint:

1. Dashboard → Settings → Webhooks → Add endpoint
2. Enter your HTTPS URL + event subscriptions
3. The dialog shows the whsec_* once — copy it to your secret manager before closing

Rotation

Both API tokens and webhook secrets support rotation with grace:

• API tokens — old and new both work for 24h after rotation. Lets you roll k8s deployment without a window of 401s.
• Webhook secrets — endpoints hold up to two active secrets; Inferio uses the new secret for new deliveries; the old one stays valid for 24h so in-flight retries still verify.

        Rotate            Window               Revoke old
        ──────────────────────────────────────────────────▶ time
        ↑                  ↑                    ↑
   new secret active   old + new both        only new
                        accepted              accepted

After the grace window, click Revoke old.

If a key leaks

1. Revoke immediately — Dashboard → Settings → API keys (or Webhooks) → Revoke
2. Audit recent activity — every request carries the token’s prefix in our audit log; download the last 30 days of activity from the dashboard and look for unfamiliar IPs / patterns
3. Rotate dependent secrets — if the leaked key sat in a .env alongside DB passwords, treat the whole file as compromised
4. Email [email protected] with the prefix of the leaked key — we’ll add it to a blocklist and flag any retries for a week

What tokens grant

Today’s tokens grant full read/write on your merchant:

• Create / cancel upload sessions
• Create / retry / delete requests + documents
• Read all extracted JSON, audit logs, confidence scores
• Configure webhook endpoints
• Read dashboard stats

Per-endpoint scopes (read-only, webhook-config-only, etc.) are on the roadmap. Today, treat every token like a production database password.

Storage recommendations

• k8s — use a Secret mounted to the pod, not env vars in the Deployment spec (env vars show up in kubectl describe)
• AWS — Secrets Manager, NOT Parameter Store (rotation hooks built in)
• Vercel / Netlify — their built-in env-var encryption is fine for marketing-grade traffic; for AP-pipeline traffic move to a real secrets manager
• GitHub Actions — repo secrets are encrypted at rest; do NOT log them via echo "$INFERIO_TOKEN" even for debugging (the runner scrubs them but containers can leak via env)