Skip to content
RocketVerifierDOCS

Get started

Authentication

In short

Send your API key in the Authorization header as Bearer rv_live_... on every request. Live keys verify any address; sandbox keys (rv_test_) only accept sandbox addresses and never charge. Each key can carry its own permissions, expiry date, IP allowlist and monthly credit cap. Apps acting for other users send an OAuth access token (rv_at_) the same way.

On this page

Every request to https://api.rocketverifier.com/v1 carries one credential in the Authorization header. The credential decides which account is billed, what the request is allowed to do and which rate limit applies.

Create an API key#

Open API keys in the dashboard and click Create API key. Give it a name that says where it runs, such as "Production signup server", and choose its settings:

SettingWhat it does
PermissionsThe scopes the key can use. All eight are selected by default.
Expiry dateOptional. The key stops working at this date.
Monthly credit limitOptional. The most credits the key can spend per calendar month (UTC).
Allowed IPsOptional. IPv4 and IPv6 addresses or CIDR ranges the key accepts requests from.
Sandbox keyCreates an rv_test_ key that only accepts sandbox addresses.

Copy the key when it appears: it is shown once. RocketVerifier stores only a SHA-256 hash, and emails the account owner whenever a key is created, rotated or revoked. Each account holds up to 25 keys.

Send the key#

Put the key in the Authorization header with the Bearer scheme. The SDKs and the CLI read ROCKETVERIFIER_API_KEY from the environment.

curl https://api.rocketverifier.com/v1/me \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"

GET /v1/me is the quickest way to check a credential: it returns the account it acts as, its balance and its scopes, and works even at a zero balance. The account reference has the full response.

The /v1 endpoints accept the Authorization header only. An X-API-Key header is ignored there.

Credential types#

The prefix tells you what a credential is and how it is billed.

PrefixCredentialBilled toUse it for
rv_live_Live API keyYour accountProduction and real addresses
rv_test_Sandbox keyNever chargedCI, staging and demos with sandbox addresses
rv_at_OAuth access tokenThe account that connected your appApps acting for other RocketVerifier users (Connect)

Organization API keys belong to a team instead of a person. They act as the organization, spend its shared credit pool and share one rate limit bucket. See organization keys below.

Permissions#

Each key carries a set of scopes, and every endpoint checks one. A key without the scope gets 403 insufficient_scope.

ScopeAllows
verify:singlePOST /v1/verify, POST /v1/finder
verify:bulkPOST /v1/verify/bulk, file uploads, previews and confirmations
jobs:readListing jobs, job status, progress, results and downloads
jobs:writeCancelling and deleting jobs
webhooks:manageCreating, updating, testing and deleting webhooks
credits:readGET /v1/credits
monitors:readListing monitors and their runs
monitors:writeCreating, updating, deleting and running monitors

Give each key only what its service needs. A signup server needs verify:single and nothing else. OAuth apps request scopes on the consent screen, including account:read; see OAuth scopes.

Expiry dates#

A key with an expiry date stops working at that moment and returns 401 api_key_expired. Use expiry for contractors, trials and one-off migrations, so access ends without anyone remembering to revoke it.

Set, extend or clear the date by editing the key. The change applies to the existing secret at once.

IP allowlists#

A key with an allowlist only accepts requests from the listed addresses. Add up to 50 IPv4 or IPv6 addresses or CIDR ranges, such as 203.0.113.7 or 10.20.0.0/16. An empty list accepts any address.

Requests from other addresses get 403 ip_not_allowed, with the caller's IP in the message so you can add it. If the client IP cannot be determined, the request is rejected too: the allowlist always fails closed.

Organization keys use the organization's allowlist instead, and it also applies to OAuth tokens issued for the organization.

Monthly spend caps#

A monthly credit limit caps what one key can spend per calendar month (UTC), from 1 to 100,000,000 credits. A leaked key or a runaway loop stops at the cap instead of draining the balance.

  • Enforced at charge time. Each charge reserves quota atomically, so concurrent requests never overshoot the cap.
  • Refunds count. Unknown results, failed jobs and cancelled jobs give their quota back.
  • Whole jobs. A bulk job is accepted only if all of its unique addresses fit under the remaining cap.
  • Resets on the first day of each month at 00:00 UTC.

A request over the cap gets 402 api_key_spend_cap_reached:

402 api_key_spend_cap_reached
{
  "error": {
    "code": "api_key_spend_cap_reached",
    "message": "This API key or app connection has reached its monthly credit limit",
    "details": { "monthly_limit": 5000, "used_this_month": 4998, "required": 10 }
  }
}

Sandbox keys never spend credits, so caps do not apply to them. OAuth connections carry their own monthly cap, set by the user who connected the app.

Rotate or revoke a key#

Rotate a key to replace its secret and keep everything else: name, permissions, expiry, allowlist, cap and usage history. The old secret stops working immediately, so deploy the new one first. Delete a key to revoke it for good.

Both actions are in the key's menu under API keys, and both send a security email to the account owner.

Organization API keys#

An organization key belongs to a team. It authenticates as the organization's owner, spends the organization's shared credit pool first when pooling is on, and uses one rate limit bucket for the whole organization, separate from members' personal keys. Its allowlist is the organization's IP allowlist.

Use organization keys for shared services, so nobody's personal key sits in a team server. Teams covers organizations, roles and pooled credits.

OAuth access tokens#

Apps that act for other RocketVerifier users use RocketVerifier Connect instead of asking for an API key. The user approves your app, and you send the access token exactly like a key:

cURL
curl -X POST https://api.rocketverifier.com/v1/verify \
  -H "Authorization: Bearer rv_at_your_access_token" \
  -H "Content-Type: application/json" \
  -d '{"email": "maya@northwind.io"}'

Calls are billed to the account that connected and limited to the scopes it approved. When an access token expires or is revoked, the API returns 401 invalid_token with a WWW-Authenticate: Bearer error="invalid_token" header. Refresh it with the rv_rt_ refresh token; the Node.js and Python SDKs do this for you when you pass the refresh token and an OAuth client.

Keep keys secure#

  • Server side only. Never ship an API key in a browser, mobile app or public repository. Use RocketShield for forms.
  • One key per service and environment. Separate keys can be capped, restricted and rotated on their own.
  • Least privilege. Grant only the scopes a service uses.
  • Restrict and cap. Add an IP allowlist for servers with fixed addresses, and a monthly credit limit on every production key.
  • Store keys as secrets. Use your platform's secret store or environment variables, never source code.
  • Rotate on any doubt. If a key appears in a log, a ticket or a commit, rotate it right away.

Authentication errors#

Every error uses the standard error shape. These are the ones a credential can cause:

Statuserror.codeCauseFix
401unauthorizedNo Authorization header, a header without Bearer , or an unknown or revoked keySend Authorization: Bearer <key> with an active key
401api_key_expiredThe key passed its expiry dateExtend the date or create a new key
401invalid_tokenThe OAuth access token expired, was revoked or its app was suspendedRefresh the token, or send the user through Connect again
403ip_not_allowedThe caller's IP is not on the key's or organization's allowlistAdd the IP or CIDR range to the allowlist
403insufficient_scopeThe key or token lacks the scope this endpoint needsAdd the scope to the key, or request it in your OAuth app
403sandbox_key_restrictedAn rv_test_ key was used on a real address or an uploadUse a live key, or a sandbox address
403insufficient_creditsThe balance is zero on an endpoint that spends creditsBuy credits, or turn on auto-recharge
403account_suspendedThe account is suspendedContact support@rocketverifier.com
402api_key_spend_cap_reachedThe key's monthly credit limit is used upRaise the limit or wait for the next month

Next steps#

Frequently asked questions

Can I use the X-API-Key header?

No. The /v1 endpoints read the key from the Authorization header only, as Bearer followed by the key. Requests with only X-API-Key are rejected with 401 unauthorized.

Can I see a key again after creating it?

No. The key is shown once, and RocketVerifier stores only a SHA-256 hash of it. If you lose a key, rotate it to get a new secret with the same settings.

Can I call the API from a browser?

Not with an API key, because anyone could copy it from the page. For forms, use RocketShield, which runs on a public key restricted to your domains. Keep API keys on your server.

How many API keys can I create?

Up to 25 per account. Use one key per service and environment, so each can be capped, restricted and rotated on its own.

Does changing a key's settings require a new key?

No. Permissions, expiry, IP allowlist and monthly cap apply to the existing secret as soon as you save, with nothing to redeploy.

Updated 11 November 2026Suggest an edit