# Aback Chess auth.md

How software agents get access to Aback Chess: the public surfaces need nothing, and a player's own account needs that player's approval.

## Who this is for

AI agents, MCP clients and the people who build them.

## What needs no credentials

- MCP server: https://abackchess.com/mcp (Streamable HTTP, read-only tools). Server card: https://abackchess.com/.well-known/mcp/server-card.json
- Public API: `GET https://abackchess.com/api/stats` and `GET https://abackchess.com/api/puzzles/daily`. Docs: https://abackchess.com/docs/api.md, described in https://abackchess.com/openapi.json
- Markdown copies of the home page, the guides and the glossary: send `Accept: text/markdown`.
- A game review in the person's own browser: `https://abackchess.com/review?pgn={PGN}&review=1` (see https://abackchess.com/.well-known/agent-skills/aback-chess/SKILL.md).

Send no `Authorization` header and no cookies to these: none is read. Requests are limited per address, about 60 a minute on the MCP server; a 429 answer says when to try again.

## A player's own account

A second MCP server, https://abackchess.com/mcp/account, reads one player's account: their saved games and Game Reviews, their puzzle rating and their practice progress. It is read-only, and it reads only what the player allowed, for as long as they allow it.

Access is OAuth 2.1, as the MCP authorization spec describes, so an MCP client that supports it needs no set-up:

1. Call https://abackchess.com/mcp/account without a token. The 401 answer's `WWW-Authenticate` header names the resource metadata, https://abackchess.com/.well-known/oauth-protected-resource/mcp/account.
2. The authorization server's metadata is at https://abackchess.com/.well-known/oauth-authorization-server.
3. Register as a public client (RFC 7591): `POST https://abackchess.com/oauth/register` with `client_name` and `redirect_uris` (https, http to localhost, or your app's own scheme). There is no client secret.
4. Send the player to https://abackchess.com/oauth/authorize with `response_type=code`, your `client_id` and `redirect_uri`, a PKCE `code_challenge` with `code_challenge_method=S256`, `state`, and optionally `scope` and `resource=https://abackchess.com/mcp/account`. They sign in themselves and choose Allow or Deny.
5. Swap the code at `POST https://abackchess.com/oauth/token` with your `code_verifier`. Access tokens last an hour; refresh tokens last 30 days and change on every use. Using one twice ends the grant.
6. Call https://abackchess.com/mcp/account with `Authorization: Bearer {access_token}`. Revoke with `POST https://abackchess.com/oauth/revoke`.

Scopes:

- `games:read`: Read the games saved to your account, and their Game Reviews
- `profile:read`: Read your puzzle rating and your practice progress

The player sees every connected app on their account page and can disconnect it at any time. A password reset disconnects every app.

## Registering by email (auth.md)

An agent that knows only its player's email address can register instead, by the auth.md `service_auth` method (the verified-email method). It is the only auth.md method offered here: anonymous registration and ID-JAG assertions answer `anonymous_not_enabled` and `identity_assertion_not_enabled`. The `agent_auth` block of https://abackchess.com/.well-known/oauth-authorization-server lists the endpoints.

1. Ask your player first: say you will connect to Aback Chess for their account and read it (the scopes below).
2. `POST https://abackchess.com/agent/identity` with JSON `{ "type": "service_auth", "login_hint": "player@example.com", "agent_name": "Your agent's name" }`. The answer has a `claim_token` (keep it in memory, never show it) and a `claim` block: a 6-digit `user_code`, a `verification_uri`, `expires_in` (600 seconds) and `interval` (5 seconds). The answer is the same whether or not an account has that address, and nothing is emailed.
3. Give your player the `verification_uri` and the `user_code` together. They open it, sign in as that email address and type the code. Only that account can confirm.
4. Poll `POST https://abackchess.com/oauth/token` with the form `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token={claim_token}`, no faster than every 5 seconds. You get `authorization_pending` until they confirm, `slow_down` if you poll too fast, and `expired_token` once the hour is up. Then, once, an `access_token` (an hour) and an `identity_assertion` (30 days).
5. If the code's ten minutes run out first, `POST https://abackchess.com/agent/identity/claim` with `{ "claim_token": "...", "email": "player@example.com" }` for a fresh `claim_attempt` block, and give your player the new code.
6. Call https://abackchess.com/mcp/account with `Authorization: Bearer {access_token}`. When it expires, `POST https://abackchess.com/oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={identity_assertion}` for a new one. There is no refresh token.

The connection shows in the player's connected apps like any other, and disconnecting it there ends the assertion too. Revoke an access token with `POST https://abackchess.com/oauth/revoke`.

## What an agent cannot reach

Nothing writes: no agent can change a game, a setting or a subscription. The player's email address, password, billing, Coach conversations and other players' data are not readable at all.

Do not sign in, create accounts or enter passwords for a person, and do not try to pass the sign-up bot check. Send them to the authorization page and let them choose there.

## Contact

support@abackchess.com
