Authentication and Scopes
How personal tokens work, the seven scopes, which scopes can cause work, the smallest set for a read-only dashboard or a status bot, and what a read-only token can't tell you.
Tip
Building your blog? You want a Content API key (rvc_), not a personal token. Revnu makes one when you set up Posts, and it can only read your published posts. See Content API.
Every request carries a personal token as a bearer header. Tokens start with rvp_, are shown once when minted, and are stored only as a SHA-256 hash.
Authorization: Bearer rvp_…Minting and revoking
In the dashboard, open Settings → Developers. Give each token a label naming the thing that will hold it (wall dashboard, reporting job, internal tooling) and only the scopes that thing needs. An account holds up to 20 live tokens, each revocable on its own. Minting needs an active trial or subscription. Scopes are fixed once a token is minted, so pick them before you press create.
Apps you connect over MCP and the CLI's revnu login mint their own tokens, labelled with the app's name, and show up in the same list.
Revnu records who did what by label. Review actions taken through the API go in the account's audit log against the token's label, block list entries carry it, and Revnu sees messages from a token as coming from API token "<label>". Give a coding agent its own token and Revnu can tell it apart from you.
Scopes
| Scope | Lets a token | Can it cause work? |
|---|---|---|
review:read |
see what is waiting for approval | No |
results:read |
read results, workflows, run history and agent status | No |
leads:read |
read leads, contacts, the block list and one person's LinkedIn state | No |
review:write |
approve, answer, choose, send, request changes, snooze, dismiss | Yes. send sends email; approve can publish a post, post to Reddit, launch ads or raise the ad budget. |
agent:message |
message Revnu and read its replies | Yes. Revnu does what a message asks, under your approval settings. |
workflows:write |
create, edit, pause, resume, run and delete workflows | Yes. A run is Revnu doing the workflow's steps, and a step that emails or messages someone sends on its own if your approval settings say Just Do It for that kind of work. |
leads:write |
set a lead's vertical, archetype and tags; add and remove block list entries | Only by removal: an unblocked company can be contacted again. |
GET /me and the setup routes need no scope, so /me works for verifying any live token.
Pick the smallest set
| The token is for | Scopes |
|---|---|
| A reporting dashboard: leads by workflow run, results | leads:read, results:read |
| The same, plus starting workflow runs from your app | leads:read, results:read, workflows:write |
| A wall screen that shows the review queue | review:read |
| A review screen people approve from | review:read, review:write |
| A status bot that answers "what's happening?" | results:read, leads:read, review:read |
| CRM sync onto the block list | leads:read, leads:write |
| A bot people ask to do work | agent:message, plus the read scopes it reports from |
A token made only of review:read, results:read and leads:read cannot send an email, publish, post, start a run or spend. Use that for status, not a prompt that says "do not act". A message with agent:message is a request Revnu acts on, and words in a message are not a permission boundary.
Two limits to know:
workflows:writeis one scope. A token that can run a workflow can also edit and delete workflows. There is no run-only scope.leads:readcovers LinkedIn lookups. Each lookup reads a profile on LinkedIn and spends one of your connected account's 50 lookups a day.
A status bot that can also explain
A read-only token gets you numbers, not reasons. No route returns how a sending inbox's warm-up is going, why a blog post failed, or what Revnu plans to do about a LinkedIn pause. Only Revnu can answer those, and asking needs agent:message. The results page lists what has a field and what doesn't.
There is no scope that lets a token ask but not act. A message is a request for work, whatever it says. The safest setup:
Keep two tokens. One with
results:read,leads:readandreview:readanswers status from the numbers. A second, labelled for what it is (such asstatus-bot-questions), holdsagent:messageand nothing else.Send questions only. "How is the warm-up on my sending inboxes going?" is a question. "Fix it" is a job. Revnu answers questions, but nothing in the scope stops a message from asking for work.
Don't interrupt. Send with
"interrupt": false, so a question never stops a job this token started.Make the settings the lock. If nothing may go out without a person, set the sending kinds of work to Ask Me First in Settings → Agent → What Needs Your Approval. Anything new that Revnu drafts then waits in Review. A sequence that is already live keeps sending its later steps; Pause or Stop Everything covers that.
Revnu records the second token's messages as API token "status-bot-questions", so GET /agent/thread on that token shows exactly what the bot asked and what Revnu said. More in Talk to Your Agent.
Changing a token's scopes
Scopes can't be edited after minting. To drop a scope, revoke the token in Settings → Developers and mint a new one with only the scopes you want. Nothing else changes.
Status codes
| Code | Meaning |
|---|---|
| 401 | Missing, malformed, unknown or revoked token |
| 402 | setup_pending: the account hasn't started its trial. Only /me and the setup routes answer. |
| 403 | The token lacks the scope this route needs. The body names it in requiredScope. |
| 404 | Unknown id, or another account's id. The two are indistinguishable on purpose. |
| 409 | The action isn't allowed right now. The body says why, or which actions are. |
| 429 | Slow down. Retry-After is in seconds. |
| 503 | Infrastructure, not your request. Honour Retry-After and retry the same call unchanged. |
Every error body is in Errors.
Keep it server-side
The API sends no 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
Which scopes does a read-only Revnu token need?
leads:read and results:read for leads, workflow runs and results; add review:read to see what is waiting. None of the three can send, publish, post, run or spend.
Can a read-only token tell me why something failed?
It reads counts and states: postsFailed, LinkedIn's pauseReason, what is waiting. For warm-up progress and the cause of a failure, ask Revnu with agent:message. Use a separate token for that, as in A status bot that can also explain.
Can a read-only token trigger a workflow run?
Starting a run takes workflows:write, which also allows editing and deleting workflows, so read-only tokens can't. Add it only to a token that must start runs.
Can a workflow run send email?
Yes, if your settings allow it. A run does the workflow's steps under your approval settings in Settings → Agent → What Needs Your Approval. Anything set to Ask Me First waits as a card in Review; anything set to Just Do It goes out. Spending money always waits.
How do I remove a scope from a token?
Revoke the token and mint a new one without that scope. Scopes are fixed when a token is minted.
Can a token send email?
Not one of its own: no scope lets a token write and send an arbitrary email. Three scopes can lead to an email going out. review:write sends a draft or reply Revnu wrote (POST /review/{id}/send). With agent:message or workflows:write, Revnu does the work a message or workflow step asks for, and sends on its own wherever your approval settings say Just Do It. A token with only read scopes can't cause a send.
I lost the token. Can I see it again?
Revnu stores only a hash, so the token is never shown again. 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.