RateGuard documentation
Rate limiting for your API in minutes. Zero-config traffic: attach a domain, verify it once, and send header-free traffic to your own hostname. Header auth keeps working everywhere, always.
What RateGuard does
Your clients keep speaking plain HTTPS to your own public hostname. RateGuard's edge accepts the request, enforces rate limits for your key in real time, and forwards the request — path, query, and method untouched — to your Backend URL.
In zero-config mode there are no client code changes: the hostname in the URL is the credential (see Choose a mode below).
Choose a mode
Clients send x-api-key and call the RateGuard endpoint directly.
No DNS work. Fastest to integrate.
Clients call your domain — the hostname identifies the key. No header, no SDK.
Needs one CNAME + one TXT record at your DNS provider.
Both modes are independent and can run at the same time on the same key.
Core terms
What clients call — your own hostname, attached to a key and verified via DNS. The Host header selects the key.
Where RateGuard forwards the verified traffic — your real API. The path, query string, and method arrive untouched.
The two must be different hostnames — a public domain identical to the Backend URL would route traffic in a loop through the edge. The dashboard blocks that pairing.
Quick start: API key only
- 1Create an API key in the dashboard and pick the "API key only" routing mode.
- 2Enter your Backend URL — where RateGuard forwards your traffic.
- 3Copy the key (it is shown once) and send it as the x-api-key header on every request.
- 4Call https://rpcguard.com/api/<your-path> — the /api prefix is stripped, the rest of the path is preserved.
Quick start: Zero-config domain
- 1Create an API key and pick the "Zero-config domain" routing mode.
- 2Enter BOTH hostnames on the connection screen: your Public API domain (what clients call) and your Backend URL (where traffic is forwarded) — they must be different.
- 3The domain attaches automatically and lands pending; the verification step lists your two DNS records.
- 4Add both records at your DNS provider — the CNAME (traffic) can even be added before you create the key.
- 5Verify: the panel re-checks every 45s while open, or click Verify now. Propagation is minutes-to-hours.
- 6Send traffic to https://<your-domain>/... with no x-api-key — you are authenticated by your hostname.
- 7Want the domain private instead? Turn on "Require API key" on the key — the same hostname then only serves requests that present the header (see Require API key below).
- 8Left the wizard? Everything above lives on in the key row's Domain panel.
After verification, the first HTTPS request may take a moment while the certificate is issued on demand.
Require API key (private posture)
Zero-config routing makes a verified hostname a public front door — anyone who can reach it calls your backend, authenticated by the Host header alone. Each key can flip that posture: the key's Require API key setting (a checkbox in the create wizard and the key's edit dialog, off by default) turns the hostname into a private API.
The domain still routes — it still identifies your key — but requests that do not carry a valid x-api-key header are refused at the edge with a 401 and never reach your backend. This keeps certificate-issuance-driven scanner traffic off your origin and out of your usage counters: refused calls consume no rate limits and are not billed or logged as usage.
The DNS setup is identical (the checklist below still applies — the domain must land on the edge for the mode to gate anything). Toggling the mode needs no key rotation and no re-verification, and takes effect for new requests within seconds of saving.
OPTIONS preflight requests are exempt and answered exactly as before: browsers cannot send custom headers during a preflight, so requiring the key there would break every browser client. Real traffic still requires the header.
DNS records
api.customer.com → rpcguard.comPoints your hostname at the RateGuard edge so caddy can serve it.
_rateguard-verify.api.customer.com IN TXT "rateguard-verification=<token>"Proves you control the domain. The exact token is shown in your key's domain panel — copy it from there, never type it by hand.
Some DNS providers auto-append the zone apex to record names — always confirm the full record name in your provider's UI.
Statuses
The domain is attached but ownership is not proven yet. Traffic to this host is rejected; the TXT record is awaited.
Ownership proven. Host-auth is live: requests without any header authenticate by hostname; header auth still works.
Re-runs the TXT lookup against the DNS system at any time — safe to click as often as propagation needs. The verification screen auto-re-checks every 45s while open.
Common mistakes
- Backend URL host == Public API domain host — the UI blocks this pairing: forwarding a domain back through the edge would loop, and is never what you want.
- CNAME at the zone apex (use ALIAS/ANAME flattening where the provider allows it, or a subdomain).
- Trailing dots in record names — some providers append the zone apex automatically; always confirm the full record name.
- Editing the TXT value — the string must include the rateguard-verification= prefix and match the panel exactly.
- High TTL on the record — propagation waits get longer; keep it low (300s) until verified.
- Pointing the CNAME at the wrong target (it must be the RateGuard edge host, not the dashboard URL).
Header-auth fallback
The classic path never goes away: send your traffic tohttps://rpcguard.com/api/...with an x-api-keyheader. Paths are never rewritten, and host-auth and header-auth are independent — a broken DNS setup never takes your integration down.