Skip to content

authentication.mdx

Latest commit

 

History

History
109 lines (80 loc) · 3.75 KB

authentication.mdx

File metadata and controls

109 lines (80 loc) · 3.75 KB
Raw
title Authentication
description Authenticate every API request with the x-scrapeunblocker-key header.

ScrapeUnblocker uses API keys for authentication. Every request must include your key in the x-scrapeunblocker-key HTTP header. Requests without a valid key are rejected.

Where to find your key

Your API key is available in your account dashboard:

app.scrapeunblocker.com

If you don't have an account yet, sign up on the pricing page - the free trial does not require a credit card.

Using your key

Pass the key as a request header:

curl -X POST "https://api.scrapeunblocker.com/getPageSource?url=https://example.com" \
  -H "x-scrapeunblocker-key: YOUR_API_KEY"
import requests

headers = {"x-scrapeunblocker-key": "YOUR_API_KEY"}
r = requests.post(
    "https://api.scrapeunblocker.com/getPageSource",
    params={"url": "https://example.com"},
    headers=headers,
)
const headers = { "x-scrapeunblocker-key": "YOUR_API_KEY" };
const res = await fetch(
  "https://api.scrapeunblocker.com/getPageSource?url=https://example.com",
  { method: "POST", headers }
);
The header name is case-insensitive, but always spelled with hyphens: `x-scrapeunblocker-key`. Do not use `X-ScrapeUnblocker-Key` in places where exact-case matters (some CDNs strip non-canonical case).

Keeping your key safe

Your API key is the only credential needed to make billable requests against your account. Treat it like a password.
  • Never commit keys to source control. Use environment variables (.env files added to .gitignore).
  • Never expose keys in client-side code. Browsers and mobile apps can read them. Always proxy requests through your own backend.
  • Rotate immediately if leaked. Generate a new key in the dashboard - the old one will keep working for a short grace period.

Environment variables

The recommended way to store your key:

SCRAPEUNBLOCKER_KEY=su_live_xxxxxxxxxxxxxxxx
import os
import requests

key = os.environ["SCRAPEUNBLOCKER_KEY"]
r = requests.post(
    "https://api.scrapeunblocker.com/getPageSource",
    params={"url": "https://example.com"},
    headers={"x-scrapeunblocker-key": key},
)
const key = process.env.SCRAPEUNBLOCKER_KEY;
const res = await fetch(
  "https://api.scrapeunblocker.com/getPageSource?url=https://example.com",
  { method: "POST", headers: { "x-scrapeunblocker-key": key } }
);

Authentication errors

An unrecognised key returns HTTP 401 Unauthorized with the plain-text body Unauthorized. Common causes:

Symptom Likely cause
401 Unauthorized with valid-looking key Trailing whitespace or newline in the header value
401 Unauthorized for every request Key was rotated in dashboard but old key still cached
401 No valid subscription Key is fine - the account has no active plan. Pick one in the dashboard
400 Missing x-scrapeunblocker-key The header was not sent at all (an empty value gives 401, not 400)
402 (not 401) Key and account are fine - quota, credit limit, or a failed payment. See 402 payment required
403 (not 401) Key is valid - the target site blocked the request. See handling failures

Full breakdown of each case in Errors - 401 unauthorized. If you've checked the above and still see 401, contact support from the help center.