API & Webhooks
Chess Scanner can act as an OAuth 2.0 provider, so you can build your own app or ecosystem on top of it. With the user's permission, your app can read their chess databases and games, and get notified in real time when something changes.
You'll work with four pieces:
- OAuth App. Register an application to get a Client ID and Client Secret.
- Authorization. Send the user through the OAuth flow to get an access token on their behalf.
- API. Use that token to read databases and games as JSON or PGN.
- Webhooks. Receive a signed HTTP callback when a game is created, updated, or deleted.
The API is read-only. It lets other systems import data and never changes a user's games or databases.
The typical flow
- Create an OAuth App and pick the permissions it needs.
- Implement the Authorization flow to get an access token for a user.
- Call the API with
Authorization: Bearer <token>. - Add a Webhook if you'd rather not poll for changes.
Base URLs
| Purpose | Base URL (example) |
|---|---|
| OAuth provider (authorize, token) | https://chessscanner.com |
| API (read databases & games) | https://api.chessscanner.com |
These base URLs are just examples. Use your real production hosts. The OAuth endpoints live on the main Chess Scanner app, and the data API runs on a separate server.
Permissions (scopes)
| Scope | Allows reading |
|---|---|
user.read | The user's basic profile (name, email, avatar) |
databases.read | The user's databases |
games.read | Games, single games, PGN export and the changes feed |
offline_access | Issues a refresh token for long-lived access |
Your app only sees what the user granted it, and the API checks the scopes on every request.