API keys and developer access

Last updated: October 17, 2026

BetterReviews has a REST API that lets you manage reviews, send review requests, and configure settings programmatically. To use it, you need an API key. This page covers how to create one, what scopes to pick, and how to keep your keys secure.

Most merchants won’t need an API key — if you’re collecting reviews through the BetterReviews admin and displaying them on your widget, everything works without one. API keys are for:

  • AI agents — giving a tool like the BetterReviews Claude Code skill access to your store
  • Custom integrations — internal tools, dashboards, or automations you’ve built

If what you actually want is for a person to look at your store.s numbers — an agency, a co-founder — you do not need an API key: invite them as a view-only dashboard viewer from Settings → Team.

  • Third-party automation — Zapier, Make, n8n, or similar platforms

Creating an API key

  1. Open the BetterReviews admin
  2. Go to Settings → Developer
  3. Click Create token

Screenshot of the Developer settings page with Create token button — manual capture, drop in here.

In the modal that appears:

  • Name — a label for the token (e.g. “Zapier”, “internal ops dashboard”). Only visible to you, helps you identify what each token is for later. The names reactiv and pdq are reserved: to connect those apps, use Settings → Integrations (see the Reactiv and PDQ guides).
  • Scopes — pick one:
    • Read & Write (default) — full access to manage reviews, settings, and review requests
    • Read only — can list reviews, stats, and settings but can’t create, approve, or delete anything. It can still run AI search and Q&A, which use your AI usage.

Click Create. The token is generated.

Screenshot of the token creation modal with scopes — manual capture, drop in here.

Important: copy the token now

The token is only shown once. We don’t store the full value — just a hash used to verify requests. If you close the modal without copying, you’ll need to create a new token.

Screenshot of the token display after creation with copy button — manual capture, drop in here.

We show the token in a highlighted field with a Copy button. Click copy, paste into wherever you need it (password manager, Zapier config, etc.), and only then close the modal.

Using the token

Every API request sends your token in an X-API-Key header (Authorization: Bearer is accepted too):

curl https://api.betterreviews.app/api/v1/reviews \
  -H "X-API-Key: ppo_YOUR_TOKEN"

See the API reference for every available endpoint.

Token format and security

  • Tokens are prefixed with ppo_ so they’re easy to recognize in logs or config files
  • Each token is scoped to a specific store — a token from one store can’t access a different store’s data, even if you have multiple BetterReviews installs
  • Tokens you create yourself don’t expire, but we recommend rotating them periodically (every 6-12 months). MCP connector tokens are the exception — they expire 90 days after creation

Where NOT to put your token

  • Client-side code — never embed an API key in JavaScript that runs in a browser. Keys there are public; anyone can read them.
  • Public git repos — use environment variables or a secrets manager
  • Unencrypted config files — especially if those files get shared or backed up somewhere

If you suspect a token has leaked, revoke it immediately and create a new one.

Revoking a token

The Developer settings page lists every active token with:

  • Its name
  • Its scopes
  • When it was last used (or “Never used”)

Click Revoke on any token and confirm. The token stops working immediately — any system using it will start getting 401 errors from the API.

MCP connector tokens (named mcp-connector) show up in the same list. These are the read-only URLs you paste into a claude.ai custom connector — the URL itself is the secret, so treat it like a password and never share it in a chat or a doc. They expire on their own after 90 days; Revoke is the kill switch if one leaks. The list shows the name, a “Read only” badge and when it was last used — not the expiry date, so note the 90-day window when you mint one (or just mint a fresh URL when the old one stops working).

Screenshot of the token list with revoke button — manual capture, drop in here.

There’s no “pause” — revoking is permanent. If you revoke a token you still need, create a new one.

Common integration patterns

Claude Code skill

The BetterReviews Claude Code skill uses an API key to let AI agents manage reviews, send links, and analyze content from your command line or CI. Install it once, paste your token when prompted, and the AI can work on your reviews with the scopes you granted.

MCP (Claude Code, Claude Desktop, claude.ai, ChatGPT)

BetterReviews is also an MCP server. In Claude Code or Claude Desktop, point the MCP client at https://api.betterreviews.app/api/v1/mcp with your token in an X-API-Key header — the AI then gets tools like search reviews, record a claim, link supporting reviews and ask a reviewer for permission. The claim-writing and permission tools need a Read & Write key; a Read only key gets the search and read tools. For claude.ai and ChatGPT custom connectors (which cannot send headers), create a read-only connector URL instead; see Revoking a token for how those show up in your list.

Zapier / Make / n8n

Create a token with Read & Write scopes, then use it in any HTTP Request step in these platforms. Our API returns standard JSON so mapping to their data types is straightforward.

Your own dashboards

If you’re building an internal tool that shows review stats, pulls recent reviews, or triggers review requests, a Read & Write token + a thin HTTP client is usually all you need. The API reference documents every endpoint.