Skip to main content
Every request to the API carries an API key as a bearer token, and the MCP server accepts the same keys. (The MCP server also lets clients 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.

Key format

  • 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:
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:

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). Older keys may hold fewer scopes; Settings marks them limited, and /me lists the scopes a key holds. 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, 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:
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.
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.

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

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.

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

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.
When an integration reads one brand, create a Brand key for it rather than a Workspace key.
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.
Read the key from an environment variable or your secret manager. Don’t log full request headers.
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.
If a key appears somewhere it shouldn’t, revoke it in Settings first and investigate second. Revocation is instant.

Next steps

Rate limits

How many requests a key can make, and how to back off.

Errors

Every problem type the API returns, with examples.
Last modified on November 18, 2026