Getting started with Chess.com OAuth 2.0 Server

Chess.com implements OAuth 2.0 and OpenID Connect (OIDC) so that third-party applications can sign users in with their Chess.com account and, with the user's consent, access parts of their account data and Chess.com APIs.

This guide covers everything you need to integrate: registering your app, the Authorization Code flow with PKCE, the exact contents of the tokens we issue, refreshing and revoking tokens, and calling Chess.com APIs.

At a glance

Issuer (`iss`)	`https://oauth.chess.com` (no trailing slash)
Authorization endpoint	`https://oauth.chess.com/authorize`
Token endpoint	`https://oauth.chess.com/token`
Revocation endpoint	`https://oauth.chess.com/revoke`
JWKS endpoint	`https://oauth.chess.com/certs`
Discovery document	`https://oauth.chess.com/.well-known/openid-configuration`
UserInfo endpoint	Not available; identity claims are delivered in the ID token
Supported grant types	`authorization_code`, `refresh_token`
Supported response type	`code`
PKCE	Supported; required for public clients. Use `S256`
Client authentication (token endpoint)	`client_secret_post` or `client_secret_basic`; none for public clients
Token signing algorithm	`RS256` (the `kid` header identifies the key in the JWKS)
`nonce`	Supported: returned as the `nonce` claim of the ID token from the code exchange
Access token lifetime	24 hours
Refresh token lifetime	1 month, rotated on every use
Authorization code lifetime	10 minutes, single use

1. Register your application

Fill in the request access form. Once we review and approve your request, we will create an OAuth client and send you its client_id (a UUID) and, for confidential clients, a client_secret.

To speed up the review, include:

Application name and logo URL. Both are shown to users on the consent screen.
Terms of Service and Privacy Policy URLs. These are linked from the consent screen.
Client type. Confidential if your app has a backend that can keep a secret (server-side web app), public if it cannot (single-page app, mobile or desktop app, device).
Redirect URIs. Every URI your app will send as redirect_uri, exactly as it will be sent. Wildcards are not supported, and matching is exact (scheme, host, path, trailing / and query string). The only exception is loopback URIs (http://127.0.0.1:{port}/... or http://[::1]:{port}/...), where any port is accepted, as recommended for native apps by RFC 8252.
Scopes you need and what you will use them for. See section 5, Scopes.

2. Authorization Code flow with PKCE

OAuth 2.0 Flow.png

Resource owner: the Chess.com user granting access to parts of their account.
Client: your application.
Authorization server: oauth.chess.com, where the user signs in and approves the request, and where your client obtains tokens.
Resource server: the Chess.com API your client calls with the access token.

Step 1: Create a code verifier and code challenge

Proof Key for Code Exchange (PKCE, RFC 7636) protects against authorization code interception and injection. It is required for public clients and strongly recommended for confidential clients.