Authentication

All API requests require authentication using an API key. Learn how to create and manage your keys securely.

Getting an API Key

Sign in to your ScrapeBadger account. Your first API key is created automatically and shown on the dashboard, where you can copy or regenerate it anytime.

Create more keys (optional)

Open the API Keys page and click Create key. Give it a name, optional notes, the APIs it may call and an optional expiry date.

Copy your key

Copy the key and store it as a secret (for example in an environment variable).

Using Your API Key

Include your API key in every request using one of these methods:

Header Authentication (Recommended)

Pass your API key in the x-api-key header. This is the recommended method as it keeps your key out of URLs and logs.

curl -X GET "https://scrapebadger.com/v1/twitter/users/elonmusk/by_username" \
  -H "x-api-key: sb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Query Parameter

Alternatively, pass your API key as a query parameter. Note that this method may expose your key in logs and browser history.

curl -X GET "https://scrapebadger.com/v1/twitter/users/elonmusk/by_username?api_key=sb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Error Responses

If authentication fails, the API returns one of these status codes:

Status	Name	Description
`401`	Unauthorized	Missing, invalid, disabled or expired API key. Check that you’re including the key correctly.
`402`	Payment Required	Insufficient credits. Purchase more credits to continue making requests.
`403`	Forbidden	The key is not permitted to call this API (`insufficient_scope`), the request came from an IP address the key doesn’t allow (`ip_not_allowed`), or the account is restricted. See below.

Error Response Format

{
  "detail": "Invalid or expired API key."
}

API Key Permissions

Every key either has access to all APIs (the default, including APIs added in the future) or is restricted to the APIs you pick — for example a key that may only call Google and Amazon. Set this when you create the key or later with Edit on the API Keys page; changes apply to the key’s very next request. Permissions are per API, matching the first path segment after /v1/: twitter, google, amazon, web, youtube, and so on. Everything under that API — including Twitter stream monitors, filter rules and the stream WebSocket — is covered by its permission. /v1/account is always allowed. A request to an API the key isn’t permitted to call is rejected before any credits are charged, with 403 and error: "insufficient_scope":

403 insufficient_scope

{
  "detail": "This API key does not have permission to use the Twitter / X API (/v1/twitter). It is restricted to: Google, Amazon. Grant the Twitter / X permission to this key at https://scrapebadger.com/dashboard/api-keys, or use a different key.",
  "error": "insufficient_scope",
  "required_scope": "twitter",
  "allowed_scopes": ["google", "amazon"]
}

The official SDKs raise PermissionDeniedError for this response, with required_scope and allowed_scopes attached.

Give each application its own key restricted to the APIs it uses. A leaked key then exposes only those APIs, and you can revoke it without touching anything else.

IP Restrictions

Limit a key to the IP addresses your servers use, so a leaked key is useless anywhere else. On the API Keys page, open Edit → IP restrictions, choose Only these addresses and add:

single addresses: 203.0.113.7, 2001:db8::1
CIDR ranges: 203.0.113.0/24, 2001:db8::/48

Add my current IP fills in the address of the browser you’re using — your servers may use a different one. Up to 100 entries per key; IPv4 and IPv6 are both supported. Changes apply on the key’s next request. A request from any other address is rejected before any credits are charged, with 403 and error: "ip_not_allowed". The response names the address we saw, so you can tell a misconfigured server from someone else using your key:

403 ip_not_allowed

{
  "detail": "This API key only accepts requests from specific IP addresses, and this request came from 198.51.100.23, which is not on its allowlist. If this is your server, add 198.51.100.23 (or its range) to the key at https://scrapebadger.com/dashboard/api-keys. If not, someone else may be using your key: rotate it.",
  "error": "ip_not_allowed",
  "client_ip": "198.51.100.23"
}

The official SDKs (0.53.0+) raise IPNotAllowedError, a subclass of PermissionDeniedError, with client_ip.

The address is taken from the network connection as it reaches Cloudflare — it can’t be set with headers such as X-Forwarded-For. Keys with IP restrictions don’t work through the hosted MCP server: its requests come from your AI assistant’s provider, not your servers. Use a separate, unrestricted key there.

Security Best Practices

Never expose keys in client-side code

API keys should only be used in server-side code. Never include them in frontend JavaScript, mobile apps, or public repositories.

Use separate keys for different environments

Create separate API keys for development, staging, and production. This makes it easier to rotate keys and track usage.

Rotate keys regularly

Periodically create new API keys and deactivate old ones. If a key is compromised, you can disable it without affecting other keys.

Managing API Keys

From the API Keys page you can:

Create multiple API keys for different projects and environments
Add notes describing what uses each key
Restrict each key to specific APIs, or allow all APIs
Limit each key to specific IP addresses or CIDR ranges
Set an expiry date after which the key stops working
Rename keys and enable or disable them without deleting them
View and copy a key again later, and see usage per key
Delete keys that are no longer needed

Working with colleagues? Teams let several accounts share one balance, with member keys and service keys managed by team admins.

Getting Started

Account

Getting an API Key

Using Your API Key

Header Authentication (Recommended)

Query Parameter

Error Responses

API Key Permissions

IP Restrictions

Security Best Practices

Never expose keys in client-side code

Use separate keys for different environments

Rotate keys regularly

Managing API Keys

​Getting an API Key

​Using Your API Key

​Header Authentication (Recommended)

​Query Parameter

​Error Responses

​API Key Permissions

​IP Restrictions

​Security Best Practices

Never expose keys in client-side code

Use separate keys for different environments

Rotate keys regularly

​Managing API Keys

Getting an API Key

Using Your API Key

Header Authentication (Recommended)

Query Parameter

Error Responses

API Key Permissions

IP Restrictions

Security Best Practices

Managing API Keys