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:
| Setting | What it does |
|---|---|
| Permissions | The scopes the key can use. All eight are selected by default. |
| Expiry date | Optional. The key stops working at this date. |
| Monthly credit limit | Optional. The most credits the key can spend per calendar month (UTC). |
| Allowed IPs | Optional. IPv4 and IPv6 addresses or CIDR ranges the key accepts requests from. |
| Sandbox key | Creates 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"import RocketVerifier from "@rocketverifier/sdk";
const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY);
const me = await rv.getMe();
console.log(me.email, me.credits);import os
from rocketverifier import RocketVerifier
rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"])
me = rv.get_me()
print(me.email, me.credits)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.
| Prefix | Credential | Billed to | Use it for |
|---|---|---|---|
rv_live_ | Live API key | Your account | Production and real addresses |
rv_test_ | Sandbox key | Never charged | CI, staging and demos with sandbox addresses |
rv_at_ | OAuth access token | The account that connected your app | Apps 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.
| Scope | Allows |
|---|---|
verify:single | POST /v1/verify, POST /v1/finder |
verify:bulk | POST /v1/verify/bulk, file uploads, previews and confirmations |
jobs:read | Listing jobs, job status, progress, results and downloads |
jobs:write | Cancelling and deleting jobs |
webhooks:manage | Creating, updating, testing and deleting webhooks |
credits:read | GET /v1/credits |
monitors:read | Listing monitors and their runs |
monitors:write | Creating, 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:
{
"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 -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:
| Status | error.code | Cause | Fix |
|---|---|---|---|
| 401 | unauthorized | No Authorization header, a header without Bearer , or an unknown or revoked key | Send Authorization: Bearer <key> with an active key |
| 401 | api_key_expired | The key passed its expiry date | Extend the date or create a new key |
| 401 | invalid_token | The OAuth access token expired, was revoked or its app was suspended | Refresh the token, or send the user through Connect again |
| 403 | ip_not_allowed | The caller's IP is not on the key's or organization's allowlist | Add the IP or CIDR range to the allowlist |
| 403 | insufficient_scope | The key or token lacks the scope this endpoint needs | Add the scope to the key, or request it in your OAuth app |
| 403 | sandbox_key_restricted | An rv_test_ key was used on a real address or an upload | Use a live key, or a sandbox address |
| 403 | insufficient_credits | The balance is zero on an endpoint that spends credits | Buy credits, or turn on auto-recharge |
| 403 | account_suspended | The account is suspended | Contact support@rocketverifier.com |
| 402 | api_key_spend_cap_reached | The key's monthly credit limit is used up | Raise 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