Skip to main content

DocsREST API and MCP server

API keys and authentication

Endpoints, auth and live samples for Audience Builder, Connect Data and CRM sync.

Base URLhttps://us-farmvision-new-api.onrender.com

Get started

API keys & auth

One header per request. Most teams only ever need their own API key, sent as a Bearer token.
CredentialHeaderWhere to get itWorks on
API key (llmcp_…)Authorization: BearerProfile → MCP & API keysEvery authenticated route except the ones marked session-only, and the MCP server
MCP access tokenAuthorization: BearerPOST /api/v1/gtmscoop/oauth/tokenSame routes as an API key; lasts 15 minutes (chat apps sign in through the MCP server instead)
Web sessionSession cookie + x-csrf-tokenSet as cookies by the sign-in endpointsEvery authenticated route, including session-only actions
Partner keyx-api-keyIssued by the GTM Scoop teamThe audience search routes only (/api/v1/*-search)
Your API key
curl -X POST "https://us-farmvision-new-api.onrender.com/api/v1/business-search/count" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":{"states":["Texas"],"employeeBuckets":["50-99"]}}'
Partner key
curl -X POST "https://us-farmvision-new-api.onrender.com/api/v1/business-search/count" \
  -H "x-api-key: YOUR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":{"states":["Texas"],"employeeBuckets":["50-99"]}}'

Shown once

Copy the key when you create it. Lost keys can't be recovered, only replaced.

Revoke anytime

Revoking in your profile cuts off every app using that key immediately.

Never both

Send Bearer or x-api-key on a request, not both together.

Which credential to use

Use your own API key for scripts, back-end jobs and code tools such as Claude Code and Cursor. Chat apps such as Claude and ChatGPT sign in through the MCP server with OAuth, so you never paste a key into them. Partner keys are only for companies the GTM Scoop team has set up to embed audience search in their own product.

Create, replace and revoke your key

  1. 1

    Sign in to the web app

    Keys are created from a signed-in browser session only. A request that tries with an API key or an MCP token gets 403: "Sign in to the web app to create a key — this can’t be done from an MCP session."
  2. 2

    Create the key

    Open Profile → MCP & API keys and create a key with a label (up to 150 characters) that says where it runs. The full key, starting llmcp_, is shown once. After that only its first 14 characters (keyPrefix) are shown.
  3. 3

    Replace it when you need to

    Each account has one key it creates itself, so creating a new one revokes the old one. Update every script that used it. Keys made when you connect a chat app are separate and stay connected.
  4. 4

    Revoke it

    The API checks the key on every request, so a revoked key fails on its next REST call. The MCP server keeps a verified key for up to 45 seconds, so an agent may finish a call in that window. Revoking a key that is already gone returns 404 "Key not found or already revoked."

The same actions as endpoints: GET /api/v1/gtmscoop/api-keys/mine lists your live keys with today's and the last seven days' call counts, DELETE /api/v1/gtmscoop/api-keys/mine/:id revokes one, and GET /api/v1/gtmscoop/api-keys/entitlement returns your tier and limits. See the API Keys reference.

Routes that need a signed-in person

A few actions need someone at the keyboard: creating keys, connecting or disconnecting a CRM or tool, sending records to Salesforce, HubSpot, Zoho, ClickHouse or Snowflake, changing or cancelling a plan, and deleting data. They answer 403 to API keys and MCP tokens. In the browser they use the session cookie, plus an x-csrf-token header on writes; a write without it gets 403 "Missing or invalid CSRF token". Each one is marked in the reference.

Partner keys

Partner keys are issued by the GTM Scoop team and go in the x-api-key header. They work only on the audience search routes (/api/v1/*-search) and carry their own per-minute limit, 60 a minute unless agreed otherwise. Send Authorization: Bearer or x-api-key on a request, never both: when both are present and differ, x-api-key is checked first as a partner key, so a normal API key there fails with 401.

Tokens for MCP clients and web sessions

  • Claude and ChatGPT connect through the MCP server's own OAuth sign-in. Its access tokens last one hour and its refresh tokens 30 days. Refresh tokens rotate: reusing an old one disconnects the app, with a 30-second grace for retries.
  • POST /api/v1/gtmscoop/oauth/token on the API issues access tokens that last 15 minutes and refresh tokens that last 180 days. A refresh returns a new access token and keeps the same refresh token.
  • A signed-in web session lasts three hours. A session token sent as a Bearer token gets a fresh one in the X-New-Access-Token header when less than ten minutes remain; a browser session gets a renewed cookie instead.

Authentication errors

StatusMessageWhat to do
401Not authorized, no tokenAdd the Authorization: Bearer header.
401Invalid or revoked API keyThe key was mistyped, replaced or revoked. Create a new one.
401Token expiredRefresh the session or MCP token, or use an API key.
401Missing or invalid x-api-keyThe partner key is wrong, or a normal key was sent in x-api-key.
403A sign-in-required messageDo this step in the web app.
403Missing or invalid CSRF tokenBrowser writes need the x-csrf-token header.
403Cross-site request refused (CSRF)A cookie-signed write came from a page outside GTM Scoop's own sites. Call from the web app, or use an API key.

Keep keys safe

  • Keep the key in an environment variable or a secret manager. Never put it in browser code, a mobile app or a repository.
  • Label the key with where it runs, so the call counts in your profile tell you which app is busy.
  • If a key leaks, create a new one: that revokes the old key at once.
  • Signing out everywhere also revokes your API keys and the keys of connected apps.

Related

Cookies on GTM Scoop

Essential cookies keep you signed in and the site secure, and are always on. Optional cookies (Google Analytics) help us understand how the site is used. They are on by default, except in the EU/EEA, the UK and Switzerland, where they stay off until you choose Accept All Cookies; choose Essential Cookies Only to turn them off. We do not use advertising cookies and we do not sell or share your personal information. The site works the same whichever you choose. We keep a record of your choice with the date, your IP address and the page you were on. Cookie Policy · Privacy Policy