Authorization

Every intelligence endpoint requires an active workspace API key, including Free geolocation and vulnerability lookups. Create a key in your workspace’s developer settings and keep it on your server. Send it as a bearer token:

curl "https://api.requestguard.com/v1/ip/8.8.8.8/geo" \
  -H "Authorization: Bearer rg_sk_live_..."

You can also send the same key with X-API-Key:

curl "https://api.requestguard.com/v1/events" \
  -H "X-API-Key: rg_sk_live_..."

Capabilities and Workspace Scope

A key belongs to one workspace and uses that workspace’s current subscriptions and shared monthly allowance. It cannot switch workspaces through a request header or administer billing, senders or members. Legacy global/configured intelligence keys are not accepted.

API area	Required plan	Lookup units
Geolocation and all package, npm, CVE and KEV vulnerability endpoints	Free or any paid workspace	One per request
Assessments and other intelligence, including website scans, email checks and device/CAPTCHA diagnostics	Any Suite or Lookups plan	One per request unless target-based
Rules, including read/update/delete	Any Suite or Lookups plan	Unmetered management
Webhooks, including read/update/delete and delivery	Suite Agency or Lookups Growth	Unmetered management
Events, CSV exports, analytics and lookup history	Any active workspace key	Unmetered workspace reads
Multiple blocklist targets and CIDR checks	Suite Business, Suite Agency or Lookups Growth	One per target or sampled address

Free includes 1,000 geolocation/vulnerability lookup units per UTC calendar month and one API key. Paid Email subscriptions retain that lookup allowance; they do not unlock full intelligence. Suite Starter includes 1,000 units, Suite Business and Lookups Developer 25,000, and Suite Agency and Lookups Growth 250,000. Compatible subscriptions combine by the highest allowance, never by addition. There are no automatic overage charges. See pricing for the full feature table.

All active keys in a workspace share usage. On downgrade, keys beyond the current limit pause in oldest-first inclusion order; they are preserved and can resume after an upgrade. A paused key returns 403 API_KEY_PAUSED. Revocation is permanent.

Monthly Quota and Bulk Admission

Single lookups consume one unit. POST /blocklists/check accepts 1–20 targets and consumes one unit per target; more than one requires bulk access. POST /cidr/check always requires bulk access. It consumes the actual sampled IPv4 address count: 2^(32-prefix) for /29–/32, otherwise seven addresses. Dashboard bulk jobs accept at most 100 targets and reserve the sum of their nested lookup costs.

The complete batch is reserved atomically before provider work. A denied capability or exhausted quota performs no lookup and consumes no units. Admitted analysis attempts count even when an upstream source fails. Repeating a lookup consumes another unit, including retries of GET requests.

Metered responses include X-RequestGuard-Quota-Limit, X-RequestGuard-Quota-Used, X-RequestGuard-Quota-Remaining and X-RequestGuard-Quota-Reset. The reset is the next UTC calendar month. Monthly exhaustion returns 402 QUOTA_EXCEEDED; endpoint burst limits return 429 RATE_LIMITED.

Optional Authentication for Go

POST /go/links supports anonymous creation. A valid RequestGuard API key is optional for account-scoped tracking and active-link reuse. If supplied, the key must be valid and included in the workspace’s current key limit; invalid keys never fall back to anonymous behavior.

Go uses its own creation rate limits and consumes no lookup units. The dedicated CAPTCHA widget/service also retains its separate contract; the /v1/captcha/test diagnostic remains a paid intelligence endpoint.

Account and Dashboard Sessions

Account, billing and dashboard routes under https://requestguard.com/api require a Hanko session, rather than an API key. X-RequestGuard-Workspace or the validated rg_workspace cookie can select a workspace in which the user has access. Cookie-authenticated mutations require the same Origin. Owners manage subscriptions, API keys, members and sender slots; included members can run dashboard lookups using the same capabilities and quota.

Browser Integrations

Keep secret API keys in server code. Cross-origin API clients require an origin configured in REQUESTGUARD_ALLOWED_ORIGINS. Preflight accepts only registered route/method pairs and the Authorization, Content-Type, X-API-Key and Accept headers. Preflight is unmetered and does not authorize the subsequent request. Approved origins can read quota headers; cross-origin cookie credentials are not enabled. Server-to-server calls do not need an Origin header.

Errors

Errors use { "error": { "code": "...", "message": "..." } }.

Status and code	Action
401 UNAUTHORIZED	Supply an active workspace API key.
402 QUOTA_EXCEEDED	Wait for the monthly reset or change the workspace plan.
403 CAPABILITY_REQUIRED	Use a plan that includes this endpoint.
403 BULK_LOOKUPS_REQUIRED	Use a plan with bulk access or submit one supported target.
403 API_KEY_PAUSED	Use an included key or restore the required key capacity.
403 ORIGIN_FORBIDDEN	Check the browser origin and requested headers.
404 LOOKUP_NOT_FOUND	Check the registered path and HTTP method.
429 RATE_LIMITED	Observe the endpoint’s cooldown before retrying.

Lookup responses are private and must not be cached. Unknown methods and paths are rejected before authentication, quota reservation or provider calls.