Authenticating requests

Every request to https://api.trustmatch.appmust include an API key. Keys are scoped to your developer account and count usage against your plan's included quota.

1. Get a key

Subscribe to any developer plan on Billing, then create a key on API Keys. The raw key (a string starting with tm_) is shown exactly once at creation time — store it somewhere safe immediately. TrustMatch never stores the plaintext key; we only hold the SHA-256 hash for validation.

2. Send the key on every request

Use either header — both are accepted. X-API-Key is the canonical choice.

X-API-Key: tm_5jR2p...8kZ
# — or —
Authorization: Bearer tm_5jR2p...8kZ

For ad-hoc testing you can also pass ?api_key=tm_... as a query parameter — never use this in production, since query strings get logged by intermediaries.

3. Handle the obvious failures

• 401 Unauthorized — key missing, malformed, or revoked. Check that the header value starts with tm_ and that the key is enabled on the API Keys page.
• 402 Payment Required — your subscription is inactive or past due. Subscriptions can be reactivated on Billing without changing your key.
• 429 Too Many Requests— short burst over your plan's rate limit. Slow down and retry; the response includes a Retry-After header.

Key rotation

Rotate by creating a new key, deploying it to your environment, then revoking the old one on the API Keys page. Revoked keys return 401 immediately. There is no grace period — make sure the new key is in production before you revoke.

Security

• Never commit a key to version control or ship one in client-side code. All TrustMatch calls should originate from your own server.
• Keep one key per environment / deployment so you can revoke surgically when something leaks.
• We only store the SHA-256 hash of your key — if you lose it, you must mint a new one. There is no recovery flow.