Skip to navigation

Welcome to the Lichess API

Free/libre, open-source chess server API

Introduction

Welcome to the reference for the Lichess API! Lichess is free/libre, open-source chess server powered by volunteers and donations.

Endpoint

All requests go to https://lichess.org (unless otherwise specified).

Clients

Rate limiting

All requests are rate limited using various strategies, to ensure the API remains responsive for everyone. Only make one request at a time. If you receive an HTTP response with a 429 status, please wait a full minute before resuming API usage.

Streaming with ND-JSON

Some API endpoints stream their responses as Newline Delimited JSON a.k.a. nd-json, with one JSON object per line.

Here’s a JavaScript utility function to help reading NDJSON streamed responses.

Authentication

Which authentication method is right for me?

Read about the Lichess API authentication methods and code examples

Personal Access Token

Personal API access tokens allow you to quickly interact with Lichess API without going through an OAuth flow.

Token Security

  • Keep your tokens secret. Do not share them in public repositories or public forums.
  • Your tokens can be used to make your account perform arbitrary actions (within the limits of the tokens’ scope). You remain responsible for all activities on your account.
  • Do not hardcode tokens in your application’s code. Use environment variables or a secure storage and ensure they are not shipped/exposed to users. Be especially careful that they are not included in frontend bundles or apps that are shipped to users.
  • If you suspect a token has been compromised, revoke it immediately.

To see your active tokens or revoke them, see your Personal API access tokens.

Authorization Code Flow with PKCE

The authorization code flow with PKCE allows your users to login with Lichess. Lichess supports unregistered and public clients (no client authentication, choose any unique client id). The only accepted code challenge method is S256. Access tokens are long-lived (expect one year), unless they are revoked. Refresh tokens are not supported.

See the documentation for the OAuth endpoints or the PKCE RFC for a precise protocol description.

Real life examples

Token format

Access tokens and authorization codes match ^[A-Za-z0-9_]+$. The length of tokens can be increased without notice. Make sure your application can handle at least 512 characters. By convention tokens have a recognizable prefix, but do not rely on this.