---
title: Authentication
description: How to register, get your API token, send it on every request, and what 401/402 responses mean.
---

# Authentication

Every BSD API uses the same token. You get it once, and it works across the
football API, all sport APIs, the Odds API, the MCP servers and the live
WebSockets. Registration is free.

## Get your token

1. Register at [sports.bzzoiro.com/register/](/register/).
2. Click the verification link we email you — your account is inactive until
   you do, and the token is created at this step.
3. Open your [dashboard](/dashboard/) and copy the API key. The dashboard also
   shows your add-on expiry dates and 30-day usage.

You can invalidate a leaked key and mint a new one at any time from the
dashboard (**Regenerate token**). The old key stops working immediately.

## Send the token

Put the key in the `Authorization` header of every request:

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/v2/events/?date_from=2026-08-02"
```

```python
import requests

headers = {"Authorization": "Token YOUR_API_KEY"}
r = requests.get("https://sports.bzzoiro.com/api/v2/events/", headers=headers)
print(r.json())
```

Also accepted, in order of preference:

| Method | Example | Notes |
|---|---|---|
| `Authorization: Token <key>` | `Authorization: Token abc123` | Recommended |
| `Authorization: Bearer <key>` | `Authorization: Bearer abc123` | For OAuth-style clients |
| `?token=<key>` query param | `/tennis/api/v2/matches/?token=abc123` | Avoid — tokens end up in logs |

WebSockets use the same key — see [Connect to live WebSockets](/docs/guides/websockets/)
for the two transports (query param or WebSocket subprotocol).

## What is free, what is paid

| Product | Price | What it unlocks |
|---|---|---|
| Free account | $0 | Football REST API (v1 + v2), football MCP, Image API, Signals API |
| Sports Addon | $5/mo | Tennis, CS2, darts, hockey, basketball and horse racing REST APIs + MCP servers |
| WebSocket addon | $3/mo | Live WebSocket channels (football + tennis) |
| Odds API | $5/mo | Multi-bookmaker odds feed at `/odds/api/` — free for everyone until 2026-08-17 |

All add-ons are bought at [/addons/](/addons/). Payments stack: buying a month
while you still have time left adds 30 days to your expiry.

## Error responses

**401 — missing or invalid token**

```json
{
  "error": "authentication required",
  "code": "authentication_required",
  "detail": "Send Authorization: Token <YOUR_TOKEN> on every request.",
  "register": "https://sports.bzzoiro.com/register/"
}
```

**402 — valid token, but the endpoint needs the Sports Addon**

```json
{
  "error": "Sports Addon required",
  "code": "addon_required",
  "detail": "Tennis, CS:GO, darts, hockey, basketball and horse racing APIs require the Sports Addon ($5/mo).",
  "pricing_url": "https://sports.bzzoiro.com/pricing/"
}
```

> **Note:** the paid gate is `402 Payment Required`, not 403. If your client
> special-cases 403, add 402 handling too.

Other errors follow one uniform shape — see
[Conventions & limits](/docs/conventions/).