Authentication

Every call carries an API key in its Authorization header. That's the whole scheme: no OAuth, no signing, no sessions. An agent with no key can ask for one for its person.

Send the key

As a bearer token, on every request:

const params = new URLSearchParams({
  "username": "nasa"
});

const res = await fetch(`https://api.scrapefield.com/v1/instagram/profile?${params}`, {
  headers: { Authorization: `Bearer ${process.env.SCRAPEFIELD_KEY}` },
});

const { data, meta } = await res.json();
console.log(data, meta.credits_charged);

Keys

A key looks like sf_live_ followed by 32 random characters. The prefix makes a leaked key easy to spot in a secret scanner.
You create keys in the dashboard. A key is shown once, when it’s created. We keep only its hash, so we can’t show it again or recover it.
An account can have 10 active keys. Give each a name, one per app or environment, so you can tell them apart in the requests log.
Revoking a key takes effect on the next call. A revoked key never works again, and stays listed so you can see what was cut off.

Limit a key to some platforms

When you create a key you can tick the platforms it may call: any of Google Maps, LinkedIn, Instagram, TikTok, X. A call to anything else is refused with scope_not_allowed, and costs nothing. A key with every platform ticked, or none, may call all of them.

Never in a URL

A key in a query string ends up in server logs, proxies and browser history, so the API refuses ?api_key= with key_in_url. The MCP server takes the key in the same header, and refuses it in a URL too.

From an agent: a key for the person you work for

An agent with no key can ask for one. It sends the person’s address; we email them a link, and the agent shows them a short code. They open the link, sign in, and type the code. Then the agent’s next check is given a key, once. Without the code nothing happens, so an email someone else’s agent caused can only be ignored.

curl -X POST "https://api.scrapefield.com/v1/signup" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "agent": "Claude Code"}'

The answer to the ask has id and user_code. Show the person the code; keep id secret, as it is worth a key, and send it only as the bearer token of GET /v1/signup, never in a URL.
Check every few seconds. The answer is pending, then approved with api_key, once; after that, delivered. A request lasts 30 minutes.
An account an agent starts has no free credits: the person buys a pack. An address that already has an account gets one more key on it, named after the agent, which they can revoke on the Keys page.
Over MCP, with no key, the tools are sign_up and check_sign_up.

Demo mode: no key at all

Any endpoint answers demo=true without a key. The answer is one fixed answer, the same whatever you ask about, in exactly the real shape, and it’s free. It is real data, captured once a week and dated in its note, which names whom it is about: mostly Ferrari. An endpoint added since the last capture answers with a sample until the next one, and its note says so. It’s meant for trying the API and for building against it before you have an account. A demo call never reaches a source, and a call that sends a key is never a demo.

Errors

Error codes
Code	HTTP	When, and what to do
`missing_api_key`	401	No Authorization header was sent. Send `Authorization: Bearer sf_live_…`. Create a key in the dashboard, or, from an agent, ask for one for your person with `POST /v1/signup`.
`invalid_api_key`	401	The key is unknown or was revoked. Check the key, or create a new one. Revoked keys never come back.
`key_in_url`	400	The key was sent as `?api_key=` in the URL. Send it in the `Authorization: Bearer …` header. A key that has been in URLs may be in someone's logs: consider revoking it.
`unverified_account`	403	Calling the API before confirming your email address. Open the link we emailed. Confirming the address adds the trial credits and signs you in.
`scope_not_allowed`	403	The key is scoped to some surfaces and this is not one of them. Use a key with the surface in its scopes, or widen the key.
`signup_not_found`	404	No sign-up request has that id. Send the `id` that `POST /v1/signup` returned as `Authorization: Bearer …`, exactly as it was. A request that has expired says `expired`; start a new one.
`key_limit`	403	The account already has as many active keys as it may: an agent's approved request makes one more. Revoke a key you no longer use on the Keys page, then ask the agent to check again.