> ## 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

> Authenticate API and MCP requests with a bearer key that reaches one brand or the whole workspace, and revoke it when you no longer need it.

Every request to the API carries an API key as a bearer token, and the [MCP server](https://docs.usequotable.com/mcp-server/overview.md) accepts the same keys. (The MCP server also lets clients [sign in with OAuth](https://docs.usequotable.com/mcp-server/authentication.md#sign-in-with-oauth); those tokens work only there, not with the REST API.) A key belongs to one workspace, holds the scopes it was created with, and reaches either one brand or the whole workspace.

```bash theme={"system"}
curl https://app.usequotable.com/api/v1/me \
  -H "Authorization: Bearer $QUOTABLE_API_KEY"
```

## Key format

```text theme={"system"}
quotable_live_9fKq2LmX7RtB4nWc8ZyH1sDv6PaE3uJo
└─────┬─────┘└──────────────┬───────────────┘
   prefix          32 random letters and digits
```

* Keys start with `quotable_live_` followed by 32 letters and digits. The fixed prefix makes a leaked key easy for secret scanners to recognize.
* The **prefix** shown in Settings and returned by `/me` is `quotable_live_` plus the first 8 random characters, for example `quotable_live_9fKq2LmX`. Use it to tell keys apart; it can't be used to authenticate.
* The full key is shown once, when you create it, and can't be retrieved later. If you lose it, create a new key and revoke the old one.

## Send the key

Send the key in the `Authorization` header with the `Bearer` scheme:

```http theme={"system"}
Authorization: Bearer quotable_live_9fKq2LmX7RtB4nWc8ZyH1sDv6PaE3uJo
```

Send the key only in the `Authorization` header. A request without a valid key gets `401 Unauthorized` with a `WWW-Authenticate: Bearer realm="api"` header and a problem body whose `detail` says why:

| `detail` | Meaning |
| - | - |
| ``Send an API key as `Authorization: Bearer quotable_live_…`.`` | No `Authorization` header, or the value isn't a well-formed key. |
| `Unknown API key.` | The key is well-formed but doesn't exist. |
| `This API key was revoked.` | Someone revoked the key in Settings. |
| `This API key has expired.` | The key passed its expiry date. |
| `The API key creator no longer has the required access.` | The person who created the key left the workspace or lost the access the key needs. See [Creator access](#creator-access). |

## Scopes

Scopes are deny-by-default: a key can call only the endpoints whose scope it holds. Keys you create in **Settings → API keys** hold every scope below, and what they can read is set by the brands they reach (see [Brand access](#brand-access)). Older keys may hold fewer scopes; Settings marks them **limited**, and `/me` lists the scopes a key holds.

| Scope | Label | Grants |
| - | - | - |
| `read:projects` | Brands | List brands and read their settings: `GET /projects`, `GET /projects/{project_id}` |
| `read:visibility` | Visibility | Prompts, daily visibility scores, cited sources and reporting rows: `/prompts`, `/visibility`, `/citations`, `/reporting/*`. In the MCP server, also shopping products. |
| `read:content` | Content | Articles, including their outline, meta tags and HTML: `/articles`, `/articles/{article_id}` |
| `read:demand` | Demand | Demand terms and their monthly AI-volume series: `/demand/terms` |
| `read:facts` | Facts | Brand facts, fact-check verdicts and the sources behind a claim: `/facts`, `/fact-checks` |
| `read:agents` | Agents | Agents, their inputs and their runs. MCP server only. |
| `read:tables` | Tables | Tables and their rows. MCP server only. |
| `write:facts` | Edit facts | Add, reword, switch off or remove facts: `POST /facts`, `PATCH` and `DELETE /facts/{fact_id}` |
| `run:agents` | Run agents | Start agent runs, which use the workspace's credits. MCP server only. |

`GET /me` needs no scope. Any valid key can call it.

`write:facts` and `run:agents` are the scopes that change data or spend credits. When you connect an MCP client by [signing in with OAuth](https://docs.usequotable.com/mcp-server/authentication.md#sign-in-with-oauth), they're never selected for you: you choose them on the approval page.

A valid key without the endpoint's scope gets `403 Forbidden`. The response names the missing scope twice, in the header and in the body:

```http theme={"system"}
HTTP/2 403
content-type: application/problem+json; charset=utf-8
www-authenticate: Bearer realm="api", error="insufficient_scope", scope="read:content"
```

```json theme={"system"}
{
  "type": "/api/v1/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This endpoint requires the read:content scope.",
  "instance": "urn:request:7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "scope": "read:content"
}
```

You can't change an existing key's scopes. If a **limited** key lacks a scope you need, create a new key, switch your integration to it, then revoke the old one.

> [!NOTE]
>
> `GET /projects/{project_id}/demand/terms` also depends on your plan: it returns data only on plans that include Prompt Volumes. On other plans it answers `404`, even with `read:demand`. See [Plans and limits](https://docs.usequotable.com/workspace/plans-and-limits.md).

## Brand access

When you create a key you choose its **Scope**, which decides the brands it can read:

* **Brand.** Only the brand you last worked in. To make a key for another brand, open that brand first. `project_ids` in `/me` lists it.
* **Workspace.** For the workspace owner, every brand, including ones added later: `project_ids` is `null` in `/me`.

A key limited to brands returns only those brands from every list endpoint, and any path with another brand's id answers `404 Not Found`.

The API returns `404` both for a brand that doesn't exist and for one outside the key's allowlist. This is deliberate: a key can't discover which ids exist in your workspace.

> [!NOTE]
>
> Integration admins can only grant brands they have access to. For them **Workspace** means the brands they can access when they create the key; brands added later aren't included.

## Who can create and revoke keys

| Role | See keys | Create and revoke keys |
| - | - | - |
| Owner | Yes | Yes, for any brand |
| Integration admin | Yes | Yes, for the brands they can access |
| Other members | Yes | No |

Creating or revoking a key is a sensitive action. If your sign-in isn't recent, Quotable asks you to sign in again, or for a fresh code from your authenticator app. Creations and revocations appear in the workspace audit log.

A workspace can hold up to **25 active keys**. Revoked keys don't count, so revoke one to make room. Key names are up to 80 characters.

For details on roles, see [Team and roles](https://docs.usequotable.com/workspace/team-and-roles.md).

## Expiry

Keys you create in Settings don't expire: `expires_at` is `null` in `/me`. Revoke a key when you no longer need it.

Some older keys were created with an expiry date. Settings shows it next to the key, and `/me` returns it as `expires_at`. After that date, requests get `401` with `This API key has expired.` Expiry can't be extended; create a replacement before the date.

> [!TIP]
>
> If your key has an `expires_at`, check it from `/me` in your integration's health check, and alert when it's less than two weeks away.

## Revocation

Select **Revoke** next to a key in **Settings → API keys**. Revocation takes effect on the very next request. Revoked keys move to a **Revoked** section, kept for the record.

## Creator access

A key acts on behalf of the workspace, but it can never read more than the person who created it currently can. Each request checks that:

* The creator is still an active member of the workspace.
* The creator is still the owner, or still an integration admin with access to every brand on the key's allowlist.

If either check fails, the key stops working with `401` and `The API key creator no longer has the required access.` Settings flags these keys with a **Creator left** badge. To restore access, have a current owner or integration admin create a replacement key.

## Last used

Settings shows when each key was last used. Use it to find keys that no integration uses anymore, and revoke them.

## Security best practices

> [accordion] One key per integration
>
> Give each integration its own key. You can revoke one without breaking the others, the last-used date tells you which integration is active, and each key has its own rate-limit allowance.

> [accordion] Reach only the brands you need
>
> When an integration reads one brand, create a **Brand** key for it rather than a **Workspace** key.

> [accordion] Keep keys on the server
>
> Call the API from your backend, a scheduled job or a serverless function. Never embed a key in a browser app, a mobile app or a public repository.

> [accordion] Store keys in a secret manager
>
> Read the key from an environment variable or your secret manager. Don't log full request headers.

> [accordion] Rotate keys
>
> Replace keys on a schedule. Create the new key, deploy it, confirm the old key's last-used date stops moving, then revoke the old key.

> [accordion] Revoke a leaked key immediately
>
> If a key appears somewhere it shouldn't, revoke it in Settings first and investigate second. Revocation is instant.

## Next steps

> [card] [Rate limits](https://docs.usequotable.com/api-reference/rate-limits.md)
>
> How many requests a key can make, and how to back off.

> [card] [Errors](https://docs.usequotable.com/api-reference/errors.md)
>
> Every problem type the API returns, with examples.


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