Authentication

Every request except test addresses and GET /v1/health needs an API key. There are two kinds.

	Secret key	Publishable key
Prefix	ibe_live_…	ibe_pub_…
Where it lives	Your server, secret manager, CI secrets	Your web page’s JavaScript
Endpoints	All /v1/*	/v1/check only
Response	Full response	Reduced response
Origin check	None	Must match an allowed origin
Limits	Your account tier (Rate limits)	Low, separate limits

Sending the key

Use either header. Both behave identically.

# Preferred
curl -s https://api.isbusinessemail.com/v1/check \
  -H "Authorization: Bearer ibe_live_…" \
  -H "Content-Type: application/json" \
  -d '{"domain":"acme.io"}'

# Alternative
curl -s https://api.isbusinessemail.com/v1/check \
  -H "X-API-Key: ibe_live_…" \
  -H "Content-Type: application/json" \
  -d '{"domain":"acme.io"}'

Never put a key in a query string.

Secret keys

• Created in the dashboard under Keys. Your first key is created automatically at first sign-in.
• Shown once. We store only a SHA-256 hash, so we can’t show it again. Lost it? Create a new one and revoke the old one.
• Up to 5 keys per account. Use one per environment or service, so you can revoke one without touching the others.
• Each key carries a checksum. Mistyped or truncated keys are rejected immediately with invalid_key, without a database lookup.
• Revocation takes effect within 60 seconds everywhere.

Publishable keys

Publishable keys let a signup form show an inline hint (“Please use your work email”) before the user submits. They are designed to be visible in page source, so they are restricted:

• They only work when the request’s Origin matches one of the allowed origins you set on the key (for example https://app.example.com). Anything else gets 403 forbidden_origin.
• They get a reduced response: category, is_business, recommendation, confidence, did_you_mean, shared_inbox, group, the top reasons and whether Google Workspace / Microsoft 365 was detected (workspace.microsoft_365_mail says whether Microsoft runs the email or the domain only has a Microsoft tenant). No is_blocked, no deep enrichment, no detailed mail or workspace blocks.
• They have low limits of their own and cannot call batch, feedback or usage.

An Origin header can be forged outside a browser, so treat a publishable key as a UX helper. Always enforce the decision on your server with a secret key. The signup form guide shows the full pattern.

Rotating a key

1. Create a new key in the dashboard.
2. Deploy it to your service (both keys work at the same time).
3. Confirm traffic on the new key in Usage.
4. Revoke the old key. It stops working within 60 seconds.

Rotate whenever someone with access leaves, after an incident, or on a schedule that suits you. Key creation and revocation trigger a notification email; the key itself is never in the email.

Leaked keys are revoked automatically

Secret keys have a recognizable ibe_live_ prefix and checksum, and we take part in GitHub secret scanning. If one of your secret keys is pushed to a public GitHub repository, GitHub reports it to us, we revoke it automatically and email you with steps to rotate. Create a new key, deploy it, and remove the old one from your git history.

Avoid leaks in the first place: keep keys in environment variables or a secret manager, add .env to .gitignore, and never ship a secret key to a browser or mobile app.

Terms acceptance

API keys belong to an account that has accepted the current Terms and Privacy Policy. When those change materially, we email you 30 days ahead. During that grace period responses carry a Warning header; after it, requests return 403 terms_not_accepted until someone on the account signs in and accepts.

Errors you may see

Code	Status	Meaning
unauthorized	401	No key sent (and the input isn’t a test address)
invalid_key	401	Malformed key or unknown key
key_revoked	401	The key was revoked (by you, an admin, or leak detection)
forbidden_origin	403	Publishable key used from an origin that isn’t allowed
terms_not_accepted	403	The account must accept updated terms

Full list: Errors.