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

# Authentication & Rate Limits

> API key authentication and rate limiting information

Every request must include a valid API key.

## Supplying the API key

Use the `x-api-key` header:

```http theme={null}
GET /platforms/twitch/profiles/12345 HTTP/1.1
Host: external-api.streamforge.com
x-api-key: YOUR_API_KEY
```

Requests without the header return `401 Unauthorized`. Unknown keys return `403 Forbidden`.

## Rate limits

Each key is provisioned with a per minute window request limit(defaults shown below; your allocations may differ):

| Window | Default allowance | Header for limit           | Header for remaining           | Reset header               |
| ------ | ----------------- | -------------------------- | ------------------------------ | -------------------------- |
| Minute | 1,000 requests    | `X-RateLimit-minute-limit` | `X-RateLimit-minute-remaining` | `X-RateLimit-minute-reset` |

When a limit is hit:

* The API returns `429 Too Many Requests`.
* Response headers still include the remaining limit and a `Retry-After` header indicating seconds until the window resets.

### Interpreting headers

Example response headers:

```
X-RateLimit-minute-limit: 1000
X-RateLimit-minute-remaining: 428
X-RateLimit-minute-reset: 1731001800
```

* `X-RateLimit-minute-limit`: Your maximum total requests per minute window.
* `X-RateLimit-minute-remaining`: How many requests you can still make within the 1 minute window.
* `X-RateLimit-minute-reset`: UNIX timestamp (seconds) when that window resets.

### Usage logging

We log every request to an internal usage stream. If you need exports for billing/reconciliation, contact support.

## Key rotation & revocation

* Keys can be rotated by the Streamforge team on request, old keys are immediately invalid.

## Best practices

* **Distribute load**: If you run high-concurrency jobs, stagger requests to avoid spikes at window boundaries.
* **Handle 429**: Implement an exponential backoff and respect `Retry-After`.
* **Monitor usage**: Use the rate-limit headers so you know when you're close to limits.