# Authentication and Scopes

> How personal tokens work, the five scopes, and which scope each route needs.

Canonical: https://revnu.com/docs/authentication

Every request carries a personal token as a bearer header. Tokens start with `rvp_`, are shown once when minted, and only ever leave your account as a SHA-256 hash.

```
Authorization: Bearer rvp_…
```

## Minting and revoking

Settings → API Tokens in the dashboard. Give each token a label naming the thing that will hold it (wall dashboard, Zapier, internal tooling) and only the scopes that thing needs. Up to 20 live tokens per account, each revocable on its own. Every API write is recorded in the account's audit log against the token's label.

## Scopes

| Scope | Lets a token |
|---|---|
| `review:read` | see what is waiting for you |
| `review:write` | approve, answer, send, request changes, snooze, dismiss |
| `agent:message` | message your agent and read its replies |
| `results:read` | read results, workflows and agent status |
| `leads:read` | read leads and contacts |

`GET /me` needs no scope at all, so it works for verifying any live token.

## Status codes

| Code | Meaning |
|---|---|
| 401 | Unknown or revoked token |
| 403 | The token lacks the scope this route needs. The body names it. |
| 404 | Unknown id, or another account's id. The two are indistinguishable on purpose. |
| 409 | The action is not allowed on that card right now. The body says which are. |
| 429 | Slow down. `Retry-After` is in seconds. |
| 503 | Infrastructure, not your request: the token could not be checked, the limiter was down for a write, or a delivery answer was lost. Honour `Retry-After` and retry the same call unchanged. A `409` is never an outage; it is a settled refusal. |

## Keep it server-side

The API does not send CORS headers. Call it from a backend, a serverless function, a bot, or the CLI, with the token in an environment variable.

## Frequently asked questions

### I lost the token. Can I see it again?

No. Only a hash is stored. Revoke it and mint a new one; it takes ten seconds and nothing else changes.

### Does a revoked token fail immediately?

Yes. Every request resolves the token fresh, so a revoked token gets 401 on its next call, including a message that is mid-wait.