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

# Authentication

> Connect an MCP client to Quotable by signing in with OAuth or with a scoped API key, and choose the workspace, data and brands each client can read.

The MCP server accepts two kinds of credential. Both read the same data, through the same scopes and brand limits:

| | OAuth sign-in | API key |
| - | - | - |
| **Best for** | Claude, ChatGPT, Claude Code and other clients that sign in to MCP servers | Clients that send a fixed header, scripts, shared setups |
| **How you set it up** | Add the server URL; the client opens a Quotable page where you approve it | Create a key in **Settings → API keys** and paste it into the client |
| **What the client sends** | A short-lived access token it renews on its own | `Authorization: Bearer quotable_live_…` on every request |
| **Where it works** | The MCP server only | The MCP server and the [REST API](https://docs.usequotable.com/api-reference/authentication.md) |
| **How you stop it** | **Disconnect** under **Connected apps** in **Settings → MCP** | **Revoke** in **Settings → API keys** |

Only the workspace owner and integration admins can approve a sign-in or create a key. Other members can see both lists.

## Sign in with OAuth

When a client that supports MCP sign-in connects to `https://app.usequotable.com/api/mcp` without a credential, Quotable answers `401` and tells the client where to sign in. The client opens a Quotable page in your browser.

**1. Sign in to Quotable**

If you aren't signed in, sign in as usual, including your second factor or single sign-on. You come back to the approval page afterwards.

**2. Check who is asking**

Check the app's name and the address it sends you back to, such as `claude.ai` or `chatgpt.com`. If either looks unfamiliar, click **Cancel**. Some connections also ask you to tick **I started this connection myself**.

**3. Pick the workspace**

The connection reads one workspace: the one you're working in. If you belong to several, switch with the buttons under **Use another workspace**.

**4. Pick the data and the brands**

Untick any data the app doesn't need, and leave **Every brand** ticked or choose specific brands. The app can never get more than the app asked for and you ticked. **Run agents** and **Edit facts** let the app act, not only read. They appear only when the app asks for them, and they start unticked.

**5. Allow access**

Click **Allow access**. Your browser returns to the app, which finishes connecting. **Cancel** tells the app you declined.

Approval links expire after ten minutes and work once. If the page says the request expired, start the connection again from the app. If you switch workspace in another tab while the page is open, **Allow access** asks you to reload, so you never approve a workspace you didn't see.

> [!NOTE]
>
> If your sign-in isn't recent, Quotable asks you to sign in again or confirm your second factor before you can allow access. It's the same check as creating an API key.

### How long a connection lasts

The client receives an access token that lasts one hour and a refresh token it uses to get the next one, so you don't sign in again every hour. If a refresh token goes unused for 30 days, the client asks you to sign in again. A refresh always returns exactly the data you approved, whatever `scope` the client sends.

A connection stops working, and the client asks you to sign in again, when:

* someone disconnects it in **Settings → MCP**;
* the client signs out of Quotable;
* the person who approved it leaves the workspace or loses the access it needs;
* Quotable detects a possible problem with the connection's tokens and ends it to be safe.

### Connected apps

**Settings → MCP** lists every approved connection under **Connected apps**: the app's name and address, the data and brands it reads, who approved it and when, and when it was last used. The owner and integration admins can click **Disconnect**; it takes effect on the app's next request. Approving and disconnecting are recorded in the audit log.

> [!NOTE]
>
> OAuth tokens are bound to the MCP server. The REST API doesn't accept them; use an API key there.

### For client developers

Quotable follows the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization):

| | |
| - | - |
| **Protected resource metadata** | `https://app.usequotable.com/.well-known/oauth-protected-resource/api/mcp` (also served at `/.well-known/oauth-protected-resource`), and in `WWW-Authenticate: Bearer resource_metadata="…"` on every `401` |
| **Authorization server metadata** | `https://app.usequotable.com/.well-known/oauth-authorization-server` |
| **Resource indicator** | `https://app.usequotable.com/api/mcp`. Send it as `resource` on the authorization and token requests; tokens are valid only for this resource. |
| **Client registration** | Dynamic client registration at `/api/oauth/register`, or a client metadata document URL as `client_id` |
| **Grant types** | `authorization_code` with PKCE (`S256` only), `refresh_token` (rotating) |
| **Client authentication** | `none` (public clients), `client_secret_post`, `client_secret_basic` |
| **Revocation** | `/api/oauth/revoke` ([RFC 7009](https://www.rfc-editor.org/rfc/rfc7009)) |
| **Scopes** | Read: `read:projects`, `read:visibility`, `read:content`, `read:demand`, `read:agents`, `read:tables`, `read:facts`. Write: `run:agents`, `write:facts`. |
| **Redirect URIs** | `https` URLs, or `http` on `localhost`, `127.0.0.1` or `[::1]` (any port). Required on the authorization request and repeated on the token request; matched exactly, except the loopback port. |

The authorization response includes `iss`. If a client asks for no scope Quotable knows, the approval page offers every read scope. A write scope is offered only when the client asks for it by name, and it starts unticked. Errors in the authorization request (a missing PKCE challenge, an unsupported `response_type`, another `resource`) are sent back to the redirect URI only for clients identified by a metadata document. For other clients they're shown on a Quotable page instead. `scope` on a refresh request is ignored.

## Use an API key

API keys suit clients that can send a fixed header, and scripts. The client sends the key in the `Authorization` header on every request:

```http theme={"system"}
Authorization: Bearer quotable_live_…
```

### Create a key

**1. Open API keys**

In Quotable, go to **Settings → API keys** and click **Create API key**. Only the workspace owner and integration admins can create and revoke keys. Other members can see the list of keys.

**2. Pick what the key can reach**

Under **Scope**, choose **Brand** for the brand you're working in only, or **Workspace** for every brand you can open. A key limited to one brand can't read any other brand.

**3. Name it after the client**

Use a name that says where the key lives, such as "Claude Code – Maria" or "Cursor – content team". The name appears in the key list next to the key's last-used date.

**4. Copy the key**

Click **Create key**. The full key, starting with `quotable_live_`, is shown once. Copy it into your client's configuration or your secret manager right away. It can't be shown again.

A key created in **Settings → API keys** gets every scope, including **Run agents** and **Edit facts**, and doesn't expire. What it can reach is set by the brand or workspace you pick. A workspace can hold up to 25 active keys.

> [!NOTE]
>
> When an integration admin creates a **Workspace** key, the key covers the brands that admin can access at that moment. Brands added later aren't included. **Workspace** keys created by the owner also cover brands added later.

## Scopes by tool

Each tool requires one scope. Scopes are deny-by-default: a key or a connection can call only the tools whose scope it was granted. On the approval page, the settings label is what you tick.

| Tool | Scope | Settings label |
| - | - | - |
| `list_projects` | `read:projects` | Brands |
| `get_visibility` | `read:visibility` | Visibility |
| `list_prompts` | `read:visibility` | Visibility |
| `list_citations` | `read:visibility` | Visibility |
| `get_shopping_overview` | `read:visibility` | Visibility |
| `get_shopping_product` | `read:visibility` | Visibility |
| `list_articles` | `read:content` | Content |
| `search_demand` | `read:demand` | Demand |
| `list_agents` | `read:agents` | Agents |
| `get_agent` | `read:agents` | Agents |
| `get_agent_run` | `read:agents` | Agents |
| `run_agent` | `run:agents` | Run agents |
| `list_tables` | `read:tables` | Tables |
| `get_table_rows` | `read:tables` | Tables |

`read:facts` (**Facts**) and `write:facts` (**Edit facts**) are used by the [REST API](https://docs.usequotable.com/api-reference/introduction.md)'s facts endpoints. No MCP tool uses them.

> [!TIP]
>
> Always grant `read:projects`. Every other tool takes a brand id, and your assistant gets those ids from `list_projects`.

Any valid key can connect and list the tools, whatever its scopes. Your client shows every tool. When the assistant calls a tool the key or connection wasn't granted, the call returns an error instead of data:

```text theme={"system"}
insufficient_scope: This tool requires the run:agents scope, which the key was not granted.
```

To fix it, disconnect the app and sign in again ticking that data, or create a new key. You can't add scopes to an existing key or connection.

### Common scope sets

These apply to OAuth connections, where you tick the data on the approval page.

| You want to | Grant |
| - | - |
| Report on visibility, competitors and citations | `read:projects`, `read:visibility` |
| Research demand behind your topics | `read:projects`, `read:demand` |
| Read agents, their runs and your tables | `read:projects`, `read:agents`, `read:tables` |
| Start agent runs from your client | `read:projects`, `read:agents`, `run:agents` |

## Limit a key or connection to some brands

A brand list applies to every tool. `list_projects` returns only those brands, and any other tool called with a brand id outside the list answers as if the brand doesn't exist:

```text theme={"system"}
not_found: No such brand in this workspace, or the key's project allowlist does not include it.
```

Both cases read the same on purpose, so a client can't discover brands it wasn't given.

> [!NOTE]
>
> The API calls brands "projects". The `project_id` that tools take is a brand's id.

## Recommended practice

> [accordion] Prefer OAuth where your client supports it
>
> A signed-in connection has no long-lived secret to copy into a file, renews itself, and shows up under **Connected apps** with who approved it.

> [accordion] Use one key per client and person
>
> Give each AI client its own key. When someone leaves or a laptop is lost, you revoke that key without breaking anyone else's setup, and the last-used date tells you which clients are active.

> [accordion] Grant the least access
>
> On the approval page, untick data the app doesn't need. A connection for a visibility report doesn't need **Run agents**. For keys, pick **Brand** when one brand is enough: an agency key for one client needs only that client's brand.

> [accordion] Revoke keys you no longer use
>
> Keys created in the app don't expire. Check the last-used dates in **Settings → API keys** and revoke keys that are no longer in use.

> [accordion] Keep the key out of shared files
>
> Don't commit keys to a repository. Most clients can read the key from an environment variable or prompt for it. Each [connect guide](https://docs.usequotable.com/mcp-server/overview.md#connect-your-client) shows how.

## Revoke a key or disconnect an app

In **Settings → API keys**, click **Revoke** next to the key. Revoking takes effect on the next request: a connected client is refused on its very next tool call with `401` and "This API key was revoked."

A key also stops working when the person who created it leaves the workspace or loses the access the key needs. Requests then fail with "The API key creator no longer has the required access." Create a new key from an active owner or integration admin.

To end an OAuth connection, click **Disconnect** next to it under **Connected apps**. The app's next request gets `401` and it asks you to sign in again.

## Next steps

> [card] [Connect a client](https://docs.usequotable.com/mcp-server/overview.md#connect-your-client)
>
> Step-by-step setup for each client.

> [card] [Tools reference](https://docs.usequotable.com/mcp-server/tools.md)
>
> Exactly what each tool returns.

> [card] [Troubleshooting](https://docs.usequotable.com/mcp-server/troubleshooting.md)
>
> Every error message and what to do about it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.