Get started
API keys & auth
| Credential | Header | Where to get it | Works on |
|---|---|---|---|
| API key (llmcp_…) | Authorization: Bearer | Profile → MCP & API keys | Every authenticated route except the ones marked session-only, and the MCP server |
| MCP access token | Authorization: Bearer | POST /api/v1/gtmscoop/oauth/token | Same routes as an API key; lasts 15 minutes (chat apps sign in through the MCP server instead) |
| Web session | Session cookie + x-csrf-token | Set as cookies by the sign-in endpoints | Every authenticated route, including session-only actions |
| Partner key | x-api-key | Issued by the GTM Scoop team | The audience search routes only (/api/v1/*-search) |
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"]}}'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
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
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, startingllmcp_, is shown once. After that only its first 14 characters (keyPrefix) are shown. - 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
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/tokenon 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-Tokenheader when less than ten minutes remain; a browser session gets a renewed cookie instead.
Authentication errors
| Status | Message | What to do |
|---|---|---|
| 401 | Not authorized, no token | Add the Authorization: Bearer header. |
| 401 | Invalid or revoked API key | The key was mistyped, replaced or revoked. Create a new one. |
| 401 | Token expired | Refresh the session or MCP token, or use an API key. |
| 401 | Missing or invalid x-api-key | The partner key is wrong, or a normal key was sent in x-api-key. |
| 403 | A sign-in-required message | Do this step in the web app. |
| 403 | Missing or invalid CSRF token | Browser writes need the x-csrf-token header. |
| 403 | Cross-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.