> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate REST and MCP requests to RevyOps.

## The `X-API-KEY` header

Every RevyOps REST endpoint under `/api/public/*` and the MCP server both authenticate with a single header:

```
X-API-KEY: <your-api-key>
```

There is no separate login step and no OAuth flow. The key alone identifies the workspace (and, for master keys, the agency) the request is allowed to touch.

If the header is missing or the key doesn't match anything on record, the request is rejected. A missing key returns "Missing API key"; an unrecognized key returns "Invalid API key".

## Where keys come from

API keys are generated and managed from **Developer → Keys** in the RevyOps dashboard. Three key types exist:

| Key type             | Prefix | Scope           | Description                                                                         |
| -------------------- | ------ | --------------- | ----------------------------------------------------------------------------------- |
| Read & write API key | `RV-`  | Client          | Full read and write access to the selected client workspace.                        |
| Read only API key    | `RO-`  | Client          | Read-only access to the selected client workspace. Safe for reporting and BI tools. |
| Master API key       | `ML-`  | Agency (master) | Access across every client in the agency's master database. Internal systems only.  |

A key is generated and revealed once in a dialog; only a masked version (prefix, dots, last 4 characters) is shown afterward. Keys can be regenerated (issues a new secret, breaks anything using the old one) or revoked from the same screen.

## Client-level vs agency-level keys

* **Client keys** (`RV-`/read-write and `RO-`/read-only) are scoped to one client workspace at a time. You pick the client in the dashboard sidebar before generating one; the key is stored against that `clientId`.
* **Master keys** (`ML-`) are scoped to the whole agency and can reach any client under it. Generating one requires master list access permission; it is not tied to a single client.

For the MCP server specifically: client discovery (see below) resolves a key through `/api/public/whoami`, which only recognizes client-scoped keys (`RV-`/`RO-`). A master key is not resolved this way and will not appear as a workspace through `list_clients`.

## Client selection for the MCP server

The MCP server accepts one or more comma-separated API keys in the `X-API-KEY` header:

```
X-API-KEY: RO-key-for-client-a, RO-key-for-client-b
```

For each key, the server calls `/api/public/whoami` to resolve it to a `client_id` and `client_name`. When a tool call doesn't specify `client_name`, the server picks a default: if only one workspace resolved, it uses that one; with multiple workspaces, it falls back to the first key's workspace. Call `list_clients` first to see every workspace your key(s) resolve to, then pass the workspace name explicitly to other tools when you have more than one.

Passing a `client_name` that doesn't match any resolved workspace (by exact name, partial name match, or client id) raises an error naming the key as invalid for that client.

## The `whoami` endpoint

`GET /api/public/whoami` resolves the calling `X-API-KEY` to workspace identity. It requires the header and returns:

```json theme={null}
{
  "client_id": "...",
  "client_name": "..."
}
```

It returns 401 if no client is found for the key. The MCP server uses this endpoint for client discovery; it is also usable directly against the REST API to confirm which workspace a given key belongs to.