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

# API Key Authentication – Sportrix Data REST and WebSocket

> Authenticate every Sportrix Data request with an API key. Learn how to pass the X-API-Key header, handle 401 and 403 errors, and manage keys.

Every request to the Sportrix Data API is authenticated with an **API key**. Keys are opaque strings prefixed with `sk_` and are issued to your account by the Sportrix Data team. There are no sessions, cookies, or OAuth flows — just include your key on every request.

<Warning>
  Keep your API key secret. Do not expose it in client-side JavaScript, mobile app bundles, or public repositories. If a key is compromised, contact support to disable it immediately.
</Warning>

## Passing your key

### REST API — `X-API-Key` header

The standard and recommended way to authenticate REST requests is the `X-API-Key` header:

```bash theme={null}
curl https://api.sportrixdata.com/api/sports \
  -H "X-API-Key: sk_your_api_key_here"
```

Include this header on every request. The only endpoint that does **not** require authentication is `GET /health`.

### WebSocket — header or query parameter

For WebSocket connections, you can authenticate using either method:

**`X-API-Key` header** (preferred for server-side clients):

```
wss://scores.sportrixdata.com/v1/stream
X-API-Key: sk_your_api_key_here
```

**`key` query parameter** (useful for browser clients that cannot set WebSocket headers):

```
wss://scores.sportrixdata.com/v1/stream?key=sk_your_api_key_here
```

The connection is rejected with HTTP `401` during the handshake if the key is invalid or lacks the required scope.

## Authentication errors

| Status             | Meaning                                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | The `X-API-Key` header (or `key` parameter) is missing, the key is unknown, or the key has been disabled or has expired |
| `403 Forbidden`    | The key is valid but does not have the scope required by the requested endpoint                                         |

All error responses include a JSON body with a `detail` field explaining the reason:

```json theme={null}
{ "detail": "Missing required scope: live_scores" }
```

## Key management

Keys are issued **per account** (called a **client** in the API). A single client account can have multiple API keys — for example, one key per environment (development, staging, production) or one per team. All keys belonging to a client inherit the same set of scopes and sport allowlist.

A key can be in any of these states:

| State    | Effect                                                                         |
| -------- | ------------------------------------------------------------------------------ |
| Active   | Requests proceed normally (subject to scopes and allowlist)                    |
| Disabled | All requests with this key receive `401 Unauthorized`                          |
| Expired  | Once the key's expiry datetime has passed, requests receive `401 Unauthorized` |

Contact support to create, disable, or adjust the expiry on a key.

## Scopes

Each key inherits the **scopes** granted to your client account. Scopes control which endpoints you can call — attempting an endpoint your key lacks permission for returns `403 Forbidden`.

| Scope                    | Grants access to                                    |
| ------------------------ | --------------------------------------------------- |
| `fixtures`               | Browse sports, leagues, and matches                 |
| `live_scores`            | On-demand live score snapshots                      |
| `live_scores_statistics` | Real-time WebSocket stream and live score snapshots |
| `final_scores`           | Half-time and full-time result snapshots            |

<Note>
  You can see which scopes your key covers in your account dashboard or by contacting support. For a full description of what each scope unlocks, see [Scopes](/concepts/scopes).
</Note>