> For the complete documentation index, see [llms.txt](https://rock-odds.gitbook.io/rock-odds-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rock-odds.gitbook.io/rock-odds-docs/authentication.md).

# Authentication

Authenticated endpoints require the RockOdds API key associated with your account.

## Recommended: request header

Send your key in the `X-API-Key` request header:

```http
GET /api/v2/games HTTP/1.1
Host: rockodds.live
X-API-Key: YOUR_API_KEY
```

```bash
curl \
  --url "https://rockodds.live/api/v2/games" \
  --header "X-API-Key: YOUR_API_KEY"
```

Use header authentication for REST requests and for SSE clients that support custom headers.

## Query parameter

The API also accepts `api_key` as a query parameter:

```
https://rockodds.live/api/v2/stream?api_key=YOUR_API_KEY
```

This option exists primarily for the browser `EventSource` API, which cannot attach a custom header.

{% hint style="warning" %}
URLs may be stored in browser history, access logs, monitoring systems, and analytics. Do not use query-parameter authentication unless your client requires it. For public browser applications, connect through your own backend so the API key is not shipped to users.
{% endhint %}

## Authentication errors

A missing or invalid key returns `401 Unauthorized`:

```json
{
  "detail": "Invalid or missing API key"
}
```

Check that:

* The header is named exactly `X-API-Key`.
* The key has no surrounding quotes or whitespace in the actual header value.
* Your environment variable is populated in the process making the request.
* The key has not been replaced or revoked.

## Keep keys safe

* Store keys in environment variables or a secret manager.
* Never commit a key to a repository.
* Never place a production key in mobile or public frontend code.
* Avoid logging full request headers or authenticated stream URLs.
* If a key may have leaked, request a replacement before continuing to use it.
