Developers

Authentication

Three kinds of credential: a secret key for your own servers and scripts, a publishable key for showing reviews on a website, and OAuth 2.1 sign-in for AI clients and apps. Every one reaches only the businesses it was given.

Secret API keys

Create them in the dashboard under Reviews MCP & API. Send the key as a bearer token on every request:

Authorization header
Authorization: Bearer gk_live_YOUR_KEY
  • A key starts with gk_live_ and is 48 characters long. It is shown once, when you create it; we keep only a SHA-256 hash, and the dashboard lists the first 12 characters so you can tell keys apart.
  • A key acts as you: it reaches the businesses you are an accepted member of, or only the ones you picked when you created it, and only with its scopes. Your role in each business still applies.
  • Up to 50 keys per user, each with an optional expiry date. A key is never edited: to change its scopes or businesses, create a new one. Revoking a key takes effect at once.
  • Replace key (next to the key in the dashboard) makes a new key with the same name, scopes and businesses; the old key stops now or in 24 hours, whichever you pick, and webhooks made with the old key move to the new one.
  • Keys belong on servers. Never put a secret key in a web page, a mobile app or a public repository; use a publishable key in the browser.
  • Dashboard session cookies are never accepted on /api/v1, and an API key cannot create or manage keys.

Scopes

A key carries the scopes you pick (a new key gets reviews:read and companies:read unless you choose others); an OAuth token carries the ones you approve. GET /v1/me needs no scope. Each operation in the API reference names the scope it needs.

ScopeLets the key or app
reviews:readSee your reviews, ratings and replies: reviews, stats, flags, Grades.com AI's queue, Review Monitoring mentions, AI Reputation answers and reports
reviews:writeReply to reviews, draft replies with AI, flag or hide reviews, connect review sites, manage Grades.com AI, send review requests and manage webhooks
companies:readSee your business details and which review sites are connected
companies:writeAdd businesses and edit their details
directory:readLook up businesses in the Grades.com directory: public listings, grades and rankings
widget_keys:writeCreate and revoke the publishable (website widget) keys of your businesses. Secret keys only, and only when you tick it; OAuth apps never get it

A missing scope answers 403 with code: insufficient_scope, required_scopes and missing_scopes in the body and WWW-Authenticate: Bearer error="insufficient_scope", scope="...". A key that has the scope while your role in the business does not allow the change gets 403 with code: role_forbidden. See Errors.

404, not 403, for other businesses

A business your credential cannot see answers 404, exactly like one that does not exist. That way company and review ids cannot be probed. If you get a 404 for a uuid you expect to work, check that the key was given that business and that you are still a member of it.

Publishable keys (websites)

A publishable key (gk_pub_...) reads the public reviews API (/v1/public/reviews, /v1/public/summary) and the review feeds. It sees only the reviews you have not hidden, so it is safe in a web page. Pass it as ?key=gk_pub_... or in the X-Grades-Key header (the header wins when both are sent).

  • Create them in the dashboard (Reviews MCP & API or Review Marketing), or with a secret key that has widget_keys:write. Up to 20 active keys per business.
  • Limit a key to your websites with up to 20 allowed origins. A browser request from another origin answers 403; server-side requests send no Origin and are allowed.
  • Yelp review text is never returned to a publishable key: a Yelp review keeps its rating, date, site and link, and text, author, avatar and response_text are null with text_policy: "aggregate".

OAuth 2.1 with PKCE (Reviews MCP and apps)

AI clients such as Claude, ChatGPT and Cursor sign in with OAuth instead of a key: the person signs in to Grades.com, sees the scopes in plain words, chooses which businesses the app may see (all, including ones added later, or only some) and approves.

Issuerhttps://app.grades.com/mcp/oauth; metadata (RFC 8414) at https://app.grades.com/mcp/oauth/.well-known/oauth-authorization-server
FlowAuthorization code with PKCE (S256, required). Clients register themselves (RFC 7591) as public or confidential clients
Redirect URIsLoopback addresses (localhost, 127.0.0.1, ::1, any port) or an allowed host of a supported AI client, HTTPS only off loopback. Contact us to get another host allowed
Access tokenA JWT that lasts 1 hour. It works on the Reviews MCP and on the REST API (Authorization: Bearer ...)
Refresh tokengk_rt_..., 90 days. It rotates: every use returns a new one, and presenting a used one again revokes the whole grant
ScopesThe scopes above except widget_keys:write, plus openid email profile. A client that asks for no API scope gets reviews:read reviews:write companies:read companies:write directory:read
RevokingPOST https://app.grades.com/mcp/oauth/revoke (RFC 7009), or Connected apps in the dashboard. A password change revokes every grant of the user

The REST API enforces a revocation at once; the MCP server re-checks tokens about once a minute. Setup per AI client: Reviews MCP. Every tool: Reviews MCP tools.