# API authentication

Create, store, use, rotate, and revoke Stats API bearer keys safely.

Canonical URL: https://stats-api.com/docs/authentication

Developer guide

## Authenticate every request.

Stats API uses bearer API keys. Keep them on a trusted server, send them in the Authorization header, and rotate each integration independently.

## Get API access

When the free signup offer is available, a newly created account receives 200 requests once, shared across all its API keys, at 30 requests per minute. No card is required, and the allowance has no expiry, automatic renewal, or monthly reset. Existing accounts keep their granted allowance and usage; older accounts without a grant are not automatically credited.

Create a key in the dashboard and make your first request with the free allowance. Paid Starter, Growth, and Scale plans are optional and retain their separate seven-day Polar trials. A paid entitlement becomes active only after verified billing confirmation.

## Send a key

Create a named key in the dashboard. The full value is shown once; Stats API stores only its SHA-256 hash.

Send the key in the HTTP Authorization header. Query-string keys are not supported because URLs commonly appear in logs, analytics, and browser history.

Example

```bash
curl "https://stats-api.com/api/v1/football/competitions?limit=10" \
  -H "Authorization: Bearer $STATS_API_KEY"
```

## Key lifecycle

Use one key per deployed application or environment so a compromised integration can be revoked without interrupting the others.

- Store keys in server-side environment variables or a secret manager.
- Never commit a key, put it in client-side JavaScript, or paste it into a public issue.
- Create a replacement before revoking an active key when rotating without downtime.
- A user may keep up to ten active keys. Revoked keys remain visible for audit history and do not count toward that active-key limit.

## Authentication errors

| HTTP | Code | Meaning |
| --- | --- | --- |
| 401 | invalid_api_key | The bearer credential is missing, malformed, unknown, or revoked. |
| 403 | subscription_inactive | The key is valid, but its account has no current API entitlement. Keep the key and restore or choose a plan. |
| 429 | rate_limit | The per-minute allowance has been exhausted. |
| 429 | monthly_quota | The subscription request allowance has been exhausted. |
| 429 | free_allowance_exhausted | The account has used its entire one-time free allowance. Choose a paid plan to continue; details.upgrade_url links to the plans. This allowance does not reset. |

---

Markdown version of https://stats-api.com/docs/authentication. Site index: https://stats-api.com/llms.txt · Full documentation and OpenAPI contract: https://stats-api.com/llms-full.txt · AI usage policy: https://stats-api.com/ai.txt