Refine Docs

Get started

Authentication

Every request to the Refine MCP server is authenticated with a personal API key sent as a bearer token. Each key is tied to a single brand, so a client only ever sees the data it’s meant to.

API keys#

A Refine key looks like this:

key format
rfn_live_abc1xyz…  (rfn_live_ + 43 random characters)

Send it on every request as the Authorization header:

header
Authorization: Bearer rfn_live_abc1xyz…

Treat keys like passwords

The full key is shown only once, at creation. Refine stores only a SHA-256 hash — we can never show it to you again. If you lose it, revoke it and create a new one. Anyone with the key can act on your brand within the limits of the attached plan.

How keys are stored

Refine persists only the hash of your key plus a short display prefix (e.g. rfn_live_abc1) so you can recognise it in a list. The 32 bytes of entropy in each key mean there’s nothing practical to brute-force, and the deterministic hash keeps lookups fast on every request.

Scoping & isolation#

Each key is bound to exactly one brand at creation time. That binding is frozen — a key can never be pointed at a different brand, and tool calls are always filtered to the key’s brand server-side. No tool takes a brand as input. To work with several brands, create one key per brand.

Access is checked again on every call, not only when the key is created. A teammate invited to a brand can create their own key for it; if they are later removed from the brand, their keys stop working on the next request, with no separate revocation needed.

1 key
maps to exactly 1 brand
1 brand
can have many keys
20 keys
max active per account

Plan gating#

Tools are gated by subscription, and the plan that counts is the brand owner’s. A teammate working on a paying brand gets the owner’s plan through their own key; there is no separate “API plan”. Creating a key requires an active plan, since a key without one could not call anything.

PlanUnlocks
VisibilityAnalytics, opportunities and citations, Search Console and Analytics data, prompts (up to 50), tags and competitors.
AutopilotEverything in Visibility, up to 200 prompts, plus content generation (30 items per type per month) and publishing.

If you call a tool your plan doesn’t cover, the server returns a clear error telling you which plan is required. Manage your plan from the subscriptions page.

Managing keys#

Keys are managed through the keys endpoint while signed in to your dashboard. The session cookie identifies you; the endpoint never accepts a bearer key to manage other keys.

Most people never need this: Settings → API keys does all three operations. The endpoint is there for scripts run by a signed-in user.

Create a key

POST /api/mcp/keys
curl -X POST https://app.refine-app.com/api/mcp/keys \
  -H "Content-Type: application/json" \
  -H "Cookie: <your dashboard session cookie>" \
  -d '{ "name": "Cursor", "brand_id": "<brand-uuid>" }'

Body fields are optional: name labels the key, brand_id picks the brand (default: your current brand, also settable with an x-brand-id header). Answers 201 with { key, plaintext, brand_name }; the plaintext appears in this response only.

StatusMeaning
401Not signed in.
403The brand’s owner has no active plan, or you have no access to that brand.
429You already hold 20 active keys. Revoke one first.

List your keys

GET /api/mcp/keys
curl https://app.refine-app.com/api/mcp/keys \
  -H "Cookie: <your dashboard session cookie>"

Returns { keys: [...] }, newest first, each with id, name, key_prefix, brand_id, created_at, last_used_at and revoked_at — never the plaintext. Revoked keys stay in the list so the history survives.

Revoke a key

Revoking is immediate and permanent. Any client using that key starts getting 401 on its next request.

DELETE /api/mcp/keys/:id
curl -X DELETE https://app.refine-app.com/api/mcp/keys/<key-id> \
  -H "Cookie: <your dashboard session cookie>"

Answers { success: true }, or 404 when the key does not exist, is not yours, or was already revoked.

Rotate regularly

Use a distinct key per client (one for Claude Desktop, one for Cursor, one for a script). If one leaks or a teammate leaves, revoke just that key without disrupting the others.

The endpoint#

All tool traffic goes to a single Streamable HTTP endpoint, over POST (and GET for the stream):

endpoint
https://app.refine-app.com/api/mcp/mcp

Unauthenticated requests are rejected with 401 before any tool runs. The server is stateless: each request stands alone, so no session needs to be kept open and no streaming notifications are sent.