Authentication

API keys

Create and manage keys in Dashboard → Settings → API Keys. Keys are scoped to your organization (tenant) and determine your plan limits. Keep them secret—do not embed in public apps.

Examples

curl -X POST https://your-domain.com/api/v1/screen \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "names": ["Vladimir Putin"], "entityTypes": ["individual"] }'

const res = await fetch("https://your-domain.com/api/v1/screen", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MATCHAUDIT_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ names:["Vladimir Putin"], entityTypes:["individual"] })
});
console.log(await res.json());

import os, requests
resp = requests.post(
  "https://your-domain.com/api/v1/screen",
  headers={"Authorization": f"Bearer {os.getenv('MATCHAUDIT_API_KEY')}",
           "Content-Type": "application/json"},
  json={"names":["Vladimir Putin"], "entityTypes":["individual"]}
)
print(resp.json())

Server-only bearer secret (usage endpoints)

Administrative/metrics endpoints like GET /api/v1/usage/summary require a server-to-server bearer secret set via API_AUTH_SECRET. Never expose this in browsers.

curl -s 'https://your-domain.com/api/v1/usage/summary?tenantId=org_123&planKey=pro' \
  -H "Authorization: Bearer $API_AUTH_SECRET"

Environments & best practices

• Use environment variables:MATCHAUDIT_API_KEY (client/server),API_AUTH_SECRET (server-only).
• Rotate keys regularly; roll without downtime by creating a new key, switching traffic, then revoking the old key.
• Least privilege: do not reuse secrets across projects.

Errors & rate limits

CORS

We send permissive CORS headers for POST/OPTIONS on public endpoints so you can call from server or browser. Prefer server-side calls to keep keys safe.

Security checklist

• Never commit keys to Git; use secrets manager/CI variables.
• Keep API_AUTH_SECRET server-only.
• Scope usage by tenant; monitor billing.usage_events.
• Rotate & revoke promptly if exposure is suspected.