rivomiAPI keys and OAuth
The two kinds of credential, the three scopes, and how each is created, bound to a workspace, and revoked.
Every credential acts as one person in one workspace. It reaches no other workspace, and membership is re-read on every request: remove the person and their credentials stop working on the next call.
Scopes
Three words that nest: send includes write, which includes read.
| Scope | Allows | Who can grant it |
|---|---|---|
read | Prospects, lists, agents, runs, conversations, the dashboard. Also pricing a post with rivomi_import_prospects and estimate_only: true. | Any member |
write | Change lists, agents, targeting and sequences; start imports and scoring runs, which spend credits. | Owner or admin |
send | Approve people for outreach, queue sequences, pause or stop them, reply on LinkedIn. | Owner or admin, once someone has accepted the LinkedIn sending terms |
Grant the narrowest scope that covers the job. A reporting agent needs read; an agent that
builds and tunes agents needs write; only an agent that approves or replies needs send.
A call outside the credential's scope fails with insufficient_scope, and the message names the
scope it needed. Nothing is partially done.
API keys
For anything you configure yourself: Claude Code, Cursor, scripts.
- In rivomi, open Settings › API and choose Create key.
- Name it after where it will live ("Cursor on my laptop"), tick its scopes, and pick an expiry
(or none). The
sendbox stays disabled until the sending terms are accepted. - Copy it. It is shown once. It is stored hashed, so a lost key is revoked and replaced.
Production keys start with pk_live_; keys from any other environment start with pk_test_.
Send the key as a bearer token on MCP and REST alike:
curl "https://rivomi.com/api/v1/workspace" \
-H "Authorization: Bearer $RIVOMI_KEY"Revoking a key under Settings › API takes effect on its next request.
OAuth
For hosted connectors (claude.ai, Claude Desktop, ChatGPT) and any client that runs the flow itself. Add the MCP URL with no key; the client sends you to rivomi to sign in, choose a workspace, and approve the requested scopes.
The grant then appears under Settings › API › Connected apps. Disconnecting it there takes effect on the app's next request.
For client authors: OAuth 2.1 with PKCE (S256), dynamic client registration, and Client ID
Metadata Documents, discoverable from /.well-known/oauth-authorization-server and the RFC 9728
protected-resource metadata. Tokens are bound to the https://rivomi.com/api/mcp
resource.