# Chessfolio authentication

Chessfolio has two agent surfaces, and they authenticate differently.

**Personal data** (a user's own games, stats and ratings) is reached with a personal access
token (PAT). Every `/api/v1/me` endpoint and every personal MCP tool returns
only the token owner's own data. This is the part that needs a token.

**Public tools** need NO token and carry no personal scope: the tournament
tools (`/api/v1/tournaments/*`; MCP `get_tournament_state`,
`estimate_round1`, `estimate_pairings`) read public Chess-Results data, the
classic-games library (`/api/v1/library*`; MCP `list_library_games`,
`get_library_game`) serves curated published games, and the ECF rating
calculator (`/api/v1/ecf/rating-change`; MCP `calculate_ecf_rating_change`)
is pure arithmetic over caller-supplied numbers.

Personal tools are read-only except five narrowly scoped mutations, each acting on one exact
game or study-collection row owned by the token holder: `attach_pgn` (REST `POST
/api/v1/me/games/{id}`) attaches validated PGN text, `request_game_review` (REST `POST
/api/v1/me/games/{id}/review`) queues or waits for an engine review,
`upload_study_game` (REST `POST /api/v1/me/study`) saves one validated PGN into the
token holder's own study collection, `request_study_analysis` (REST `POST
/api/v1/me/study/{id}/review`) is the study collection's review equivalent, and
`delete_study_game` (REST `DELETE /api/v1/me/study/{id}`) removes one study game and its
notes from that collection. None can alter results, ratings or other metadata, none accepts
URLs, paths or arbitrary files, and none touches another user's data.

## Getting a token

(You only need a token for personal data; the public tools — tournament, library and ECF calculator — work without one.)

1. Sign in (human, via Clerk) at https://chessfolio.io/login
2. Go to Settings → API access
3. Create a token — it is shown once; store it securely. Revoke any time.

## Using it

- REST: `Authorization: Bearer cfp_…` against https://chessfolio.io/api/v1/*
  (OpenAPI: https://chessfolio.io/openapi.json)
- MCP: streamable HTTP at https://chessfolio.io/api/mcp with the same header
  (works with claude.ai custom connectors and Claude Code today)

## Properties

- Five narrow writes: `attach_pgn` accepts one parseable game as PGN text, strips comments/variations, and stores parser-generated canonical PGN; `request_game_review` queues (or optionally waits up to 45s for) an engine review of a game that already has moves — an already-reviewed game is returned free; `upload_study_game` saves one validated PGN into the token holder's own study collection; `request_study_analysis` reviews a stored study game from the same shared allowance; `delete_study_game` removes one owned study game and its notes (the underlying analysed game record is untouched)
- Owner-scoped: a personal-data token can access only its creator's data
- Hashed at rest, revocable, rate-limited (120 requests/minute per user; PGN attachments, study uploads and newly queued reviews each also 20/hour, in separate buckets — the reviews bucket is one shared allowance covering both `request_game_review` and `request_study_analysis`)
- No OAuth yet — PATs first; OAuth will follow if third-party demand appears

## Public tools (no token)

The tournament tools are not the only unauthenticated surface — three tool
families need no token at all: the tournament tools (`get_tournament_state`,
`estimate_round1`, `estimate_pairings`), the classic-games library
(`list_library_games`, `get_library_game`), and the ECF rating calculator
(`calculate_ecf_rating_change`). None carries personal scope, and each is
rate-limited to 60 requests/minute in its own bucket, so a busy day on one
cannot lock out the others — REST calls are limited per caller IP; MCP calls
share one bucket per family, since the MCP protocol carries no client address
to key on.

The tournament tools alone read public Chess-Results data (source:
chess-results.com). Their Round-1 and next-round pairing outputs are
ESTIMATES, not official pairings, and snapshots may be stale; those honesty
rules travel in the payloads and tool descriptions.

Human documentation: https://chessfolio.io/developers