# API keys and OAuth

> The two kinds of credential, the three scopes, and how each is created, bound to a workspace, and revoked.

Source: https://rivomi.com/docs/connect/authentication



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 [#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 [#api-keys]

For anything you configure yourself: Claude Code, Cursor, scripts.

1. In rivomi, open **Settings › API** and choose **Create key**.
2. Name it after where it will live ("Cursor on my laptop"), tick its scopes, and pick an expiry
   (or none). The `send` box stays disabled until the sending terms are accepted.
3. 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:

```bash
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 [#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.