# Chessfolio authentication

Chessfolio has two agent surfaces, and they authenticate differently.

**Personal data** (a user's own chess record) 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 tournament tools** (`/api/v1/tournaments/*` and the
`get_tournament_state`, `estimate_round1` and `estimate_pairings` MCP
tools) read public Chess-Results data and need NO token. They carry no
personal scope.

Everything is read-only.

## Getting a token

(You only need a token for personal data; the tournament tools 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

- Read-only: there are no write endpoints on either surface
- Owner-scoped: a personal-data token only ever reads its creator's data
- Hashed at rest, revocable, rate-limited (120 requests/minute per user)
- No OAuth yet — PATs first; OAuth will follow if third-party demand appears

## Public tournament tools (no token)

The tournament tools are the one unauthenticated surface. They read public
Chess-Results data (source: chess-results.com), carry no personal scope, and
are rate-limited per IP (60 requests/minute). The 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