> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with the ScrapeBadger API using API keys.

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

## Getting an API Key

<Steps>
  <Step title="Sign in">
    [Sign in](https://scrapebadger.com/auth/signin) to your ScrapeBadger account. Your first API key is created automatically and shown on the [dashboard](https://scrapebadger.com/dashboard), where you can copy or regenerate it anytime.
  </Step>

  <Step title="Create more keys (optional)">
    Open the [API Keys](https://scrapebadger.com/dashboard/api-keys) page and click **Create key**. Give it a name, optional notes, the APIs it may call and an optional expiry date.
  </Step>

  <Step title="Copy your key">
    Copy the key and store it as a secret (for example in an environment variable).
  </Step>
</Steps>

## 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.

```bash theme={null}
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.

```bash theme={null}
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. |

```json Error Response Format theme={null}
{
  "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](https://scrapebadger.com/dashboard/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"`:

```json 403 insufficient_scope theme={null}
{
  "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.

<Tip>
  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.
</Tip>

## IP Restrictions

Limit a key to the IP addresses your servers use, so a leaked key is useless anywhere else. On the [API Keys](https://scrapebadger.com/dashboard/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:

```json 403 ip_not_allowed theme={null}
{
  "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`.

<Note>
  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](/mcp/overview): its requests come from your AI assistant's provider, not your servers. Use a separate, unrestricted key there.
</Note>

## Security Best Practices

<CardGroup cols={1}>
  <Card title="Never expose keys in client-side code" icon="shield">
    API keys should only be used in server-side code. Never include them in frontend JavaScript, mobile apps, or public repositories.
  </Card>

  <Card title="Use separate keys for different environments" icon="key">
    Create separate API keys for development, staging, and production. This makes it easier to rotate keys and track usage.
  </Card>

  <Card title="Rotate keys regularly" icon="triangle-exclamation">
    Periodically create new API keys and deactivate old ones. If a key is compromised, you can disable it without affecting other keys.
  </Card>
</CardGroup>

## Managing API Keys

From the [API Keys](https://scrapebadger.com/dashboard/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](/teams) let several accounts share one balance, with member keys and service keys managed by team admins.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.