Authentication & API keys

Every programmatic request to the ScrapeIt API authenticates with an API key that belongs to your workspace. Keys start with the sk_ prefix.

Sending the key

Two equivalent ways - pick one:

x-api-key header (recommended)Authorization Bearer

bash

curl -X POST "https://api.scrapeit.io/api/v1/scrape/web" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SCRAPEIT_API_KEY" \
  -d '{"url": "https://example.com"}'

bash

curl -X POST "https://api.scrapeit.io/api/v1/scrape/web" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SCRAPEIT_API_KEY" \
  -d '{"url": "https://example.com"}'

Requests without a valid key are rejected with HTTP 401 and the stable error code INVALID_API_KEY. A valid key of a blocked workspace gets HTTP 403 ORGANIZATION_ACCESS_DENIED instead: the key is fine, contact support to restore the workspace.

Key lifecycle

Property	Behaviour
Creation	Dashboard → Workspace → API Keys. The full key is displayed exactly once; only a hash plus a short prefix is stored.
Display	Everywhere else the key appears masked (prefix only), e.g. `sk_live_live1234_••••••••`.
Scopes	Each key carries permission scopes (for example `scrape:web`). A key without the required scope gets HTTP 403 `PERMISSION_DENIED` with the missing scope in `error.details.required_scope`.
Revocation	Revoke a key any time in the dashboard; revoked keys fail immediately.
Rotation	Create a new key, switch your integration, then revoke the old one - zero-downtime rotation.

A key belongs to the member who created it. A developer can revoke or rotate only their own keys; an owner or an admin can revoke or rotate any key of the workspace. When a member is removed from the workspace, their keys are revoked; when their role changes, the keys with scopes the new role does not hold are revoked. Integrations using a revoked key get 401 INVALID_API_KEY, so give a long-lived integration a key created by an owner or an admin.

Which endpoints accept which credentials?

API surface	API key (`x-api-key` / `Bearer sk_…`)	Dashboard session (JWT)
`POST /api/v1/scrape/web`	✅ (`scrape:web`)	✅
`POST /api/v1/scrape/web/async`, `GET /api/v1/scrape/web/async/{id}`	✅ (`scrape:web`)	✅
Site APIs: `GET /api/v1/scrape/google/search`, `/scrape/google/maps/{search,place}`, `/scrape/amazon/{search,product,best-sellers}`, `/scrape/walmart/{search,product}`, `/scrape/booking/{search,hotel}`, `/scrape/yelp/{search,business}`, `/scrape/redfin/{search,property}`, `/scrape/airbnb/{search,listing}`, `/scrape/tripadvisor/{search,place}`, `/scrape/yellowpages/{search,business}`, `/scrape/ebay/{search,item}`, `/scrape/glassdoor/{listing,job,companies,company}`, `/scrape/zillow/{listing,property}`, `/scrape/allegro/{listing,offer}`, `/scrape/apartments/{listing,property}`	✅ (`scrape:web`)	✅
`POST /api/v1/scrape/batch/web` (+ status/results/stop)	✅ (`scrape:batch`)	✅
`POST /api/v1/scrapers/crawler/jobs`	✅ (`scrapers:run`)	✅
`POST /api/v1/scrapers/{zillow,allegro,apartments,booking,yelp,walmart}/jobs`, `POST /api/v1/scrapers/{amazon-search,amazon-product,amazon-best-sellers,google-search,google-maps,google-maps-reviews,redfin,airbnb,tripadvisor,yellow-pages,ebay,glassdoor}/jobs`	✅ (`scrapers:run`)	✅
`GET /api/v1/scrapers/jobs/{id}` (+ `/results`), `GET /api/v1/scrapers/{site}/jobs/{id}`	✅ (`scrapers:read`)	✅
`GET /api/v1/jobs` (+ `/recent`), `GET /api/v1/jobs/{id}`, `GET /api/v1/scrape/requests/{id}` (+ `/attempts`, `/events`)	✅ (`scrapers:read`)	✅
`DELETE /api/v1/scrapers/jobs/{id}`, `DELETE /api/v1/scrape/jobs/{id}`	✅ (`scrapers:stop`)	✅
`GET /api/v1/files`, `GET /api/v1/files/{id}/content`, `GET /api/v1/files/{id}/raw`	✅ (`files:read`)	✅
`GET /api/v1/usage/me`	✅ (`usage:read`)	✅
MCP server `/api/v1/mcp`	✅ (each tool its endpoint's scope)	-
File download tokens, Webhooks (incl. the request webhook signing secret)	-	✅
Public status `GET /api/v1/public/status`	no credentials needed	no credentials needed

File download tokens and webhook management are workspace APIs used by the dashboard and authenticate with your dashboard session only.

Scopes map to products:

Scope	Grants
`scrape:web`	Web Scraping API (sync and async) and every one-call site API: Google SERP, Google Maps, Amazon, Walmart, Booking.com, Yelp, Redfin, Airbnb, Tripadvisor, Yellow Pages, eBay, Glassdoor, Zillow, Allegro and Apartments.com.
`scrape:batch`	Batch jobs. Stopping a batch through `DELETE /api/v1/scrape/jobs/{id}` needs it in addition to `scrapers:stop`.
`scrapers:run`	Starting Website Crawler jobs and the no-code bulk jobs - Zillow, Allegro, Apartments.com, Booking.com, Yelp, Walmart, Amazon, Google, Redfin, Airbnb, Tripadvisor, Yellow Pages, eBay and Glassdoor (they spend credits).
`scrapers:read`	Reading crawler and bulk job status and results, the unified jobs list and request diagnostics.
`scrapers:stop`	Stopping running crawler, bulk and batch jobs.
`files:read`	The file list, text preview and full download (`/raw`).
`usage:read`	`GET /api/v1/usage/me`.

A key only holds the scopes chosen when it was created - creating a key never adds scopes to existing keys. Keys created before the crawler and bulk jobs accepted API keys (October 2026) had scrapers:* removed, because back then it granted nothing: create a new key for crawler or bulk-job automation. A workspace member can grant only scopes their own role holds (a developer, for example, cannot grant scrapers:run or scrapers:stop); the dashboard's Create API key form lists only the scopes your role can grant.

A key always acts inside the workspace it was created in. The x-organization-id header the dashboard sends is ignored for API-key requests, so a key cannot read or stop another workspace's jobs - a job id from another workspace answers 404.

bash

# Start a crawl with an API key that has scrapers:run
curl -X POST "https://api.scrapeit.io/api/v1/scrapers/crawler/jobs" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SCRAPEIT_API_KEY" \
  -d '{"urls": ["https://example.com"], "maxDepth": 1, "limit": 20}'

# Poll it (scrapers:read) and stop it (scrapers:stop)
curl "https://api.scrapeit.io/api/v1/scrapers/jobs/CRAWLER_JOB_ID" -H "x-api-key: YOUR_SCRAPEIT_API_KEY"
curl -X DELETE "https://api.scrapeit.io/api/v1/scrapers/jobs/CRAWLER_JOB_ID" -H "x-api-key: YOUR_SCRAPEIT_API_KEY"

A crawl started with a key is recorded in the audit log against that key, not against a user; only the key id is stored, never the secret.

Security practices

Never commit keys. Load them from an environment variable (SCRAPEIT_API_KEY in our examples) or a secret manager.
Split keys per environment/integration so one leak has a small blast radius and usage is attributable.
Watch usage. The dashboard Usage page and GET /api/v1/usage/me show credit consumption per period; unexpected spikes are a leak indicator.
Code snippets are masked by default. The Playground and these docs always show the YOUR_SCRAPEIT_API_KEY placeholder; your real key only appears if you explicitly paste it locally.

Quickstart - first request in two minutes.
Requests & responses - envelope and correlation ids.
Error codes - every stable error code including auth failures.

Authentication & API keys ​

Sending the key ​

Key lifecycle ​

Which endpoints accept which credentials? ​

Security practices ​

Related pages ​

Authentication & API keys

Sending the key

Key lifecycle

Which endpoints accept which credentials?

Security practices

Related pages