Authentication: API keys, errors and plan limits

curl -s 'https://api.reqbeat.com/v1/whoami' -H "X-API-Key: $REQBEAT_API_KEY"
# or
curl -s 'https://api.reqbeat.com/v1/whoami' -H "Authorization: Bearer $REQBEAT_API_KEY"

GET /v1/whoami is the probe endpoint: it is never billed, and it answers with what the key resolves to — your customer_id, account_id, the plan tier the key runs on (tier, tier_name) and the key's scopes. Connector platforms use it as the connection test; you can too.

The four refusals, and what each one means

• 401 — no key. The request carried neither header. Body: {"detail":"Missing API key: send an X-API-Key header or an Authorization: Bearer token"}.
• 403 — bad key. A key was sent but it is invalid or has been revoked. Body: {"detail":"Invalid or revoked API key"}. The fix is a fresh key: rotate it from a key you still hold, or sign in and mint a new one. In Zapier or Make, a 401 or 403 means reconnect the account.
• 402 — the key works, the plan is spent. The key is over its plan's call quota, or the account passed its spend cap. The body says which (reason: quota_exceeded or spend_cap_exceeded), carries the quota counters, and includes an upgrade_url — the connector apps surface it as "upgrade your Reqbeat plan".
• 429 — too fast. Per-key limit over a 60-second window, set by the plan. Honor Retry-After and the RateLimit-* headers and the call succeeds on the retry.

Managing keys is self-serve

A key you hold can manage the keys on its own account — no dashboard round-trip, no support ticket:

• GET /v1/keys — every key on the account, active and revoked, with last_used_at.
• POST /v1/keys — mint another key for the same account. The new key's account and tier always come from the key that authorized the mint, never from the request.
• POST /v1/keys/{id}/rotate — mint the replacement and revoke the old key in one call, built for unattended agents rotating their own credential.
• DELETE /v1/keys/{id} — revoke. Keys of other accounts 404, so a leaked id reveals nothing.

Give each integration its own key: when you unplug a tool, revoke its key and nothing else changes.

What a free key can do vs a paid one

Scopes aside, every key is bounded by its plan: a daily call quota and a per-minute rate, both visible live on /v1/pricing:

A free key is a real key: the same endpoints, the same webhooks, a smaller allowance. Exhausting it returns the structured 402 above rather than silently degrading, so an automation built on the free tier fails loudly and upgrades cleanly. Plans, watch allowances and spend caps are on pricing.