# Authentication

Source: https://docs.rocketverifier.com/authentication

> 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.

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](https://app.rocketverifier.com/dashboard/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:

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

Node.js:

```js
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);
```

Python:

```python
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](https://docs.rocketverifier.com/api/account) 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](https://docs.rocketverifier.com/sandbox) |
| `rv_at_` | OAuth access token | The account that connected your app | Apps acting for other RocketVerifier users ([Connect](https://docs.rocketverifier.com/oauth)) |

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](#organization-api-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](https://docs.rocketverifier.com/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:

```json
{
  "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](https://app.rocketverifier.com/dashboard/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](https://docs.rocketverifier.com/teams) covers organizations, roles and pooled credits.

## OAuth access tokens

Apps that act for other RocketVerifier users use [RocketVerifier Connect](https://docs.rocketverifier.com/oauth) instead of asking for an API key. The user approves your app, and you send the access token exactly like a key:

cURL:

```bash
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](https://docs.rocketverifier.com/oauth/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](https://docs.rocketverifier.com/integrations/widget) 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](https://docs.rocketverifier.com/errors). 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

- [Sandbox and testing](https://docs.rocketverifier.com/sandbox)
Test with fixed results and keys that never charge.
- [Rate limits](https://docs.rocketverifier.com/rate-limits)
Requests per minute for each plan, and how to handle 429.
- [Build an app](https://docs.rocketverifier.com/oauth)
Act for other users with OAuth instead of API keys.
- [Errors](https://docs.rocketverifier.com/errors)
Every error code, its cause and how to recover.

## 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.
