Skip to main content

​
The X-API-KEY header

Every RevyOps REST endpoint under /api/public/* and the MCP server both authenticate with a single header:
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: 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:
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:
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.