Authentication & Rate Limits

Every request must include a valid API key.

Supplying the API key

Use the x-api-key header:

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.

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.

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.

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

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

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.