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

# Authenticate with The Stats API

> Every request to The Stats API requires a Bearer token. Learn how to get your API key and add it to your requests.

Every endpoint in The Stats API requires authentication. Authentication is handled via a Bearer token passed in the `Authorization` header of each HTTP request. There are no cookie-based sessions or API key query parameters — the header is the only supported method.

<Steps>
  <Step title="Get your API key">
    Log in to your account dashboard and navigate to **API Keys**. Generate a new key and copy it somewhere safe — the full key value is only shown once. If you lose it, you can revoke it and generate a replacement.
  </Step>

  <Step title="Add it to your request headers">
    Include the following header in every request you make to the API. Replace `YOUR_API_KEY` with the key you copied from the dashboard:

    ```http theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```
  </Step>

  <Step title="Make your first request">
    With your key in place, make an authenticated request to any endpoint. The example below fetches the list of available competitions:

    ```bash theme={null}
    curl --request GET \
      --url https://api.thestatsapi.com/api/football/competitions \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    A successful response returns a `200 OK` with the competitions data. If you see a `401` error instead, double-check that your key is correct and has not been revoked.
  </Step>
</Steps>

<Note>
  Keep your API key secret. Never embed it in client-side code, commit it to version control, or expose it in a public repository. Use environment variables or a secrets manager to inject the key at runtime in server-side environments.
</Note>

## Authorization header format

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

The header name is `Authorization`. The value must begin with the literal string `Bearer ` (note the trailing space) followed immediately by your API key.

## Authenticated request example

```bash theme={null}
curl --request GET \
  --url https://api.thestatsapi.com/api/football/competitions \
  --header "Authorization: Bearer YOUR_API_KEY"
```

## Error responses

If your API key is missing or invalid, the API returns a `401 Unauthorized` response with the following JSON body:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Provide a valid Bearer token in the Authorization header.",
    "status_code": 401
  }
}
```

Common causes of a `401` error:

* The `Authorization` header is absent from the request
* The token is malformed (e.g., missing the `Bearer ` prefix)
* The API key has been revoked or has expired
* There is a typo or extra whitespace in the key value