Authentication

Use this page to send your API key correctly, keep it off the browser and fix 401 and 403 errors.

Fastest way: ask your AI. Follow Build with AI, and add this to your prompt: “Read my TheStatsAPI key from the THESTATSAPI_API_KEY env var and only call the API from server code, never from the browser.”

Send the header

Every request needs this header, except /health:

Authorization: Bearer YOUR_API_KEY

The value must start with Bearer (capital B), then one space, then your key.
bearer in lowercase, a missing space or extra spaces all fail with 401.
The header is the only way to send the key. A key in the URL is ignored.

curl "https://api.thestatsapi.com/api/football/competitions?per_page=1" \
  -H "Authorization: Bearer $THESTATSAPI_API_KEY"

const res = await fetch("https://api.thestatsapi.com/api/football/competitions?per_page=1", {
  headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` },
});
console.log(res.status, await res.json());

import os
import requests

res = requests.get(
    "https://api.thestatsapi.com/api/football/competitions",
    params={"per_page": 1},
    headers={"Authorization": f"Bearer {os.environ['THESTATSAPI_API_KEY']}"},
)
print(res.status_code, res.json())

Get and manage keys

Manage keys on the API keys page in your dashboard.

Create: a new key is shown only once. Copy it into your environment variables or secrets manager straight away.
Revoke: a revoked key stops working at once and returns 401 Invalid API key.
Several keys: you can have up to 5 active keys, for example one per app or environment. Each key has its own per-minute rate limit, and all your keys share your account’s monthly quota. See Rate limits.

Keep your key on the server

Read the key from an environment variable in server code. Never hard-code it.

THESTATSAPI_API_KEY=YOUR_API_KEY

// Run with: node --env-file=.env server.mjs (Node 20.6+), or load .env with the dotenv package
const apiKey = process.env.THESTATSAPI_API_KEY;
if (!apiKey) throw new Error("THESTATSAPI_API_KEY is not set");

import os

api_key = os.environ["THESTATSAPI_API_KEY"]  # or load .env with the python-dotenv package

Add .env to your .gitignore. If you have a web frontend, have it call your own server route, and let only that route call TheStatsAPI. For example, a Next.js route handler:

app/api/next-fixture/route.js

export async function GET() {
  const res = await fetch(
    "https://api.thestatsapi.com/api/football/matches?team_id=tm_9145&status=scheduled&sort=utc_date&per_page=1",
    { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
  );
  return Response.json(await res.json(), { status: res.status });
}

Never put your key in browser code. The API allows cross-origin requests from any website, so a request from the browser will work, but anyone can then read your key from the page or the network tab. In particular:

Don’t use NEXT_PUBLIC_ or VITE_ variables for the key. They’re bundled into the browser code.
In Lovable, store the key with the Add secret form and call the API from a server function or Edge Function. Lovable commits .env, so the key must not go there.
Don’t commit the key or paste it into logs, screenshots or support tickets.

If a key leaks, create a new one, update your server, then revoke the old one.

Auth errors

Auth errors use the standard error envelope:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing authorization header",
    "status_code": 401
  }
}

Status	`code`	`message`	Fix
401	`UNAUTHORIZED`	`Missing authorization header`	Add the `Authorization` header.
401	`UNAUTHORIZED`	`Invalid authorization format. Use: Bearer <api_key>`	Start the value with `Bearer` and one space.
401	`UNAUTHORIZED`	`Invalid API key`	Check for typos, a missing character or extra spaces. Revoked keys also return this.
403	`KEY_REVOKED`	`API key has no active subscription plan`	Your account has no active plan. See pricing.
403	`FORBIDDEN`	`Account is inactive`, `API key is inactive` or `API key has expired`	Check your subscription and keys in the dashboard.
403	`ADDON_REQUIRED`	Names the add-on the endpoint needs	Add it to your subscription, or use a different endpoint.
429	`RATE_LIMITED`, `USAGE_LIMIT_EXCEEDED`	Per-minute limit or monthly quota reached	Wait for the `Retry-After` header. See Rate limits.

Every authenticated response, including errors after your key is accepted, also carries your rate-limit and quota headers. See Rate limits.

Get started

Guides

Core concepts

Send the header

Get and manage keys

Keep your key on the server

Auth errors

​Send the header

​Get and manage keys

​Keep your key on the server

​Auth errors

Send the header

Get and manage keys

Keep your key on the server

Auth errors