Authentication
How API keys work, what they are scoped to, and how they fail.
Every request except GET /health needs an API key, sent as a bearer token:
Authorization: Bearer rc_live_…There is no other authentication scheme. Query-string keys, cookies and the
X-API-Key header are not accepted on the customer API.
Creating and revoking keys
Keys are managed at registercheck.de/api-management. A key is displayed once, at creation. Losing it means revoking it and creating another.
Revocation takes effect immediately, on the next request.
What a key is scoped to
A key belongs to your account, not to a project or an environment. Every key you hold reads and writes the same lists and the same monitoring subscriptions, and draws on the same credit balance. Use separate names to tell them apart in the usage breakdown; do not expect them to be isolated from one another.
Limits are shared across all of your keys
The per-30-day request limit is enforced on your account, not on the individual key. Creating a second key does not give you a second allowance — see Rate limits.
Checking a key works
GET /health needs no key and tells you the API is reachable. To check the key itself,
use the cheapest authenticated call:
curl -sS -o /dev/null -w '%{http_code}\n' \
"https://api.registercheck.de/v1/search/suggestions?search_term=test&limit=1" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY"200 means the key is good. For anything else, see below.
Authentication failures
| Status | Body | What it means |
|---|---|---|
400 | Authorization header missing or invalid | No Authorization header, or it does not start with Bearer . |
401 | UNAUTHORIZED | The key is wrong, revoked, or your account has run out of requests for the current 30-day window. |
402 | INSUFFICIENT_CREDITS | The key is valid; the account has no credits left for this call. |
A 401 does not always mean a bad key
The same 401 UNAUTHORIZED is returned for a revoked key and for an account that has
exhausted its 30-day request allowance. Before rotating a key in response to a 401,
check your usage — a fresh key will fail in exactly the same way. This is a known
shortcoming of the current error mapping.
Keeping keys safe
- Keys carry the full permissions of your account, including deleting lists and monitoring subscriptions. Treat one as a password.
- Never ship a key in browser code. Every call in these docs is a server-side call.
- Rotate by creating the new key, deploying it, then revoking the old one — in that order.