docs/refresh_headers.md

# Fotmob API access

**As of 2026-08-20, fotmob's data API needs no credentials.** There is nothing
to refresh. If `fotmob_session.py` reports a failure, it is almost certainly an
endpoint change, not an auth problem — read the failure detail it prints.

## History

Fotmob used to gate `/api/*` behind an `x-mas` header and a Cloudflare Turnstile
challenge, proven by two cookies: `turnstile_verified` and `g_state`. This doc
previously told you to copy those two cookies into `.env` every few weeks.

That gate is gone. Browsers no longer set `turnstile_verified` at all, and
`g_state` turned out to be a Google Sign-In cookie unrelated to fotmob's API.
Verified 2026-08-20: `/api/data/leagues`, `/api/data/fixtures`,
`/api/data/matchDetails`, `/api/data/teams`, and `/api/data/allLeagues` all
return 200 JSON with no cookies whatsoever.

The `u:location` cookie is still sent, but it is a location *preference* (pins
responses to IST/India formatting), not a credential.

`FOTMOB_TURNSTILE_TOKEN` and `FOTMOB_G_STATE` are no longer read by any code and
can be deleted from `.env`.

## Health check

```
.venv\Scripts\python.exe fotmob_session.py
```

- `[OK] Fotmob API reachable (no credentials required).` — all good.
- `[FAIL] HTTP 404 ...` — the endpoint moved. Update `_HEALTH_URL` in
  `fotmob_session.py`, and check whether `scrape_luigi.py`'s `fixtures` /
  `matchDetails` paths moved too.
- `[FAIL] HTTP 401/403 ...` — fotmob re-introduced an auth gate. Open
  <https://www.fotmob.com/> in Chrome, DevTools (F12) → **Network** tab, click
  any `/api/data/...` request, and compare its **Request Headers** against
  `build_headers()`. Whatever is new is what you need to replicate.
- `[FAIL] got HTML instead of JSON` — served a page rather than the API; same
  fix as 404.

## A note on diagnosing this

The previous version of `check_alive()` returned `status_code == 200` and the
caller logged "cookies STALE" for *any* failure. It spent weeks reporting a
credential problem for what was actually a dead health-check endpoint
(`/api/data/tls`, now 404). The current `check_status()` returns the real reason
— trust what it says over any assumption that cookies expired.