# TrophyCoach authentication

How agents authenticate to each TrophyCoach surface.

## Public content (no auth)

- Website pages, guides, and tools: no authentication. Markdown representations
  are available via `Accept: text/markdown` or the `.md` URL suffix
  (e.g. `https://trophycoach.com/index.md`).
- `GET /api/gpt/markdown/{path}`: no authentication.
- `GET /llms.txt`, `GET /openapi.json`, `GET /.well-known/*`: no authentication.

## Agent API (/api/gpt/*) — API key

- **Scheme**: static API key in the `x-api-key` request header.
- **Scope**: all `/api/gpt/*` endpoints except `/api/gpt/markdown/{path}`.
- **How to get a key**: keys are issued for approved integrations (the
  TrophyCoach GPT for ChatGPT and the Gemini Gem use this API). Request access
  via the contact form: https://trophycoach.com/contact
- **Errors**: every non-2xx response is JSON with a typed envelope (see
  "Errors" below); `401 unauthorized` on a bad or missing key,
  `503 service_unavailable` if the API is disabled.
- **Rate limit**: 300 requests per 60s per API key
  (per IP when no key is presented). Every response carries
  `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`
  (Unix seconds); a `429 rate_limited` response adds `Retry-After` (seconds).
- **Spec**: https://trophycoach.com/openapi.json

## Errors

All `/api/gpt/*` errors use one JSON envelope, `Content-Type: application/json`:

```json
{ "error": { "code": "not_found", "message": "Player not found", "docs": "https://trophycoach.com/auth.md" } }
```

`details` (object) is present when there is machine-readable context, e.g.
validation issues. Codes: `invalid_request`, `unauthorized`, `not_found`, `rate_limited`, `unavailable_for_legal_reasons`, `internal_error`, `upstream_error`, `service_unavailable`.
Status mapping: 400 invalid_request · 401 unauthorized · 404 not_found ·
429 rate_limited · 451 unavailable_for_legal_reasons · 500 internal_error ·
502 upstream_error · 503 service_unavailable.

## API versioning and deprecation

- **Current version**: `2026-08-24` (date-based). Every `/api/gpt/*`
  response echoes it in the `API-Version` header; the OpenAPI spec's
  `info.version` matches.
- **Additive changes** (new endpoints, new optional fields) ship without a
  version bump. Clients must ignore unknown fields.
- **Breaking changes** ship as a new dated version. The retiring version keeps
  working for at least **90 days**, during which its responses carry
  `Deprecation` and `Sunset` headers (RFC 8594) with the retirement date,
  and the change is announced here and in the OpenAPI changelog
  (`info.description`).
- **Sunset**: after the sunset date the old behavior returns
  `410 Gone` with the Error envelope pointing at the replacement.

## MCP server — no account, pay-per-call (x402/USDC)

- **Endpoint**: https://mcp.trophycoach.com/api/mcp (Streamable HTTP,
  MCP protocol 2025-06-18).
- **No API key, no account.** `get_meta_overview` is free and lists all
  other tools with their prices.
- **Paid tools** use the [x402 protocol](https://docs.x402.org): the server
  responds `402 Payment Required` with payment requirements; the agent pays
  in USDC (gasless for the payer via EIP-3009) and retries with the payment
  header. Per-call prices: https://trophycoach.com/pricing.md
- **Flow**: initialize -> tools/list -> call `get_meta_overview` (free) ->
  call a paid tool -> receive 402 -> settle via x402 -> retried call returns
  the result.

## User accounts (humans)

Pro subscriptions (https://trophycoach.com/pricing.md) are for human users via the web
app; there is no OAuth flow for agents today. Agents should use the API key
or MCP surfaces above.