Authentication

All requests require a Bearer token in the Authorization header. API keys are prefixed with kh_live_. Every endpoint in the API — Create Search and Get Search Status — accepts this header.

Authorization: Bearer kh_live_YOUR_API_KEY

Keep keys secret. Never expose API keys in client-side code, public repositories, or browser requests. Use environment variables or a secrets manager.

Request a Key

The Keeper Health API is a paid product. To request a developer API key, email company@keeperhealth.com with:

• A short description of your use case
• Your expected request volume (searches per day or month)
• The organization the key will be billed to

Our team will provision an account and email you a kh_live_ key directly. Store it in a secrets manager or environment variable — never commit it to source control.

Rotate a Key

If you believe an API key has been leaked, exposed in a public repository, or committed to source control, rotate it immediately.

1. Email company@keeperhealth.com from the address associated with your account.
2. Include the first 8 characters of the compromised key (e.g. kh_live_a1b2c3d4) — never send the full key.
3. Briefly describe how the leak occurred so we can confirm the scope of the rotation.

We will issue a new key and revoke the compromised one. Revocation is immediate: any request made with the old key after rotation will return 403 forbidden with error.type: "forbidden" (see the full error envelope). Update your environment variables and redeploy before the old key is revoked to avoid downtime.

Prevention. Use a secrets manager (AWS Secrets Manager, Google Secret Manager, HashiCorp Vault, Doppler, etc.) rather than committing keys to .env files. Add .env to .gitignore and scan your repository history with tools like git-secrets before pushing.

Security Best Practices

1. Store your API key in a secret manager, not in source control. Use environment variables or your platform's secret store.
2. Use a different key per environment (dev, staging, prod). If one leaks, you only have to rotate one.
3. Use descriptive names when requesting keys. If you need multiple keys, each one should identify its purpose (e.g. "Acme billing pipeline" vs "Acme internal dashboard").
4. Rotate on personnel changes. If an engineer leaves, ask us to revoke keys they had access to.
5. Never share signed download_urls in tickets, chat logs, or public repos. They expire in an hour but can expose data in the meantime.
6. Monitor for 401 and 403 responses. These indicate an auth problem that should trigger an alert in your system.

Help

The API distinguishes between two authentication failure modes. Both follow the standard error envelope:

• 401 unauthorized — the Authorization header is missing, malformed, or the key value is not recognized. Fix the header or the key value.
• 403 forbidden — the key is syntactically valid but has been revoked or the organization is inactive. Request a new key; do not retry.

If your request returns 401 unauthorized, check that:

• The Authorization header is formatted exactly as Bearer kh_live_... (note the space after Bearer)
• The key value matches what was emailed to you, with no leading or trailing whitespace
• You are hitting https://api.keeperhealth.com and not a staging URL

If your request returns 403 forbidden, the key itself is no longer active. Email company@keeperhealth.com to request a new key.

For anything else — onboarding, billing, quota adjustments, or integration questions — reach out to company@keeperhealth.com and our team will respond within one business day.

See also

• Quickstart — your first request end to end
• Create Search — the endpoint every key is used on
• Errors — the full error envelope and type taxonomy
• Rate Limits — per-key quotas and Retry-After handling