Authentication

Overview

Lichess uses OAuth2 for API authentication. You’ll need an OAuth token to:

Access private user data
Create games or challenges
Make moves as a bot
Manage account settings

Many API endpoints work without authentication. Only use OAuth when you need access to protected resources.

Creating an OAuth App

Go to https://lichess.org/account/oauth/app and create a new OAuth app.Provide:

Name: Your application name (shown to users)
Description: What your app does
Redirect URI: Where users return after authorization

Get your credentials

After creating the app, you’ll receive:

Client ID: Public identifier for your app
Client Secret: Keep this confidential!

Choose your scopes

Request only the permissions your app needs. Available scopes are listed below.

OAuth Scopes

Scopes define what your app can access:

Scope	Description
`preference:read`	Read user preferences
`preference:write`	Modify user preferences
`email:read`	Read user email address
`challenge:read`	Read incoming challenges
`challenge:write`	Create and accept challenges
`challenge:bulk`	Create bulk pairings (tournaments)
`study:read`	Read private studies
`study:write`	Create and modify studies
`tournament:write`	Create tournaments
`racer:write`	Create puzzle races
`puzzle:read`	Read puzzle activity
`team:read`	Read team information
`team:write`	Manage team memberships
`team:lead`	Lead teams (kick members, etc.)
`follow:read`	Read followed players
`follow:write`	Follow/unfollow players
`msg:write`	Send direct messages
`board:play`	Play games via Board API
`bot:play`	Play games as a bot
`engine:read`	Read engine evaluations
`engine:write`	Request engine analysis
`web:mod`	Moderator actions (if authorized)

Request the minimum scopes needed. Users are more likely to authorize apps that request fewer permissions.

Authorization Code Flow

The standard OAuth2 flow for web applications:

Redirect user to authorization URL

https://lichess.org/oauth?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=preference:read%20challenge:write&
  state=RANDOM_STRING

Parameters:

response_type=code (required)
client_id - Your app’s client ID
redirect_uri - Must match your registered URI
scope - Space-separated scope list (URL encoded)
state - Random string to prevent CSRF attacks

User authorizes your app

Lichess shows the user what permissions you’re requesting. They can approve or deny.

Receive authorization code

User is redirected back to your app:

YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=RANDOM_STRING

Verify the state parameter matches what you sent.

Exchange code for access token

POST to token endpoint:

curl -X POST https://lichess.org/api/token \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d redirect_uri=YOUR_REDIRECT_URI \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

Response:

{
  "token_type": "Bearer",
  "access_token": "lio_xxxxxxxxxxxxx",
  "expires_in": 31536000
}

Personal API Tokens

For personal scripts or testing, create a personal token:

Go to https://lichess.org/account/oauth/token
Select required scopes
Click “Create”
Copy your token (starts with lip_)

Personal tokens have full access to your account. Never share them or commit them to version control.

Using Access Tokens

Include the token in the Authorization header:

curl https://lichess.org/api/account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch('https://lichess.org/api/account', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

import requests

headers = {
    'Authorization': f'Bearer {access_token}'
}
response = requests.get('https://lichess.org/api/account', headers=headers)

Token Expiration

OAuth tokens expire after 1 year by default
Personal tokens don’t expire unless revoked
Expired tokens return 401 Unauthorized
Request a new token when needed (no refresh tokens)

Revoking Tokens

Users can revoke your app’s access at https://lichess.org/account/oauth/token. When a token is revoked:

API requests return 401 Unauthorized
Your app should handle this gracefully
Prompt the user to re-authorize if needed

Security Best Practices

Store tokens securely

Never expose tokens in client-side code
Use environment variables or secure key storage
Encrypt tokens in your database
Never commit tokens to version control

Use HTTPS

Always use HTTPS for OAuth redirects
Never send tokens over unencrypted connections
Validate SSL certificates

Validate state parameter

Generate a random state value for each authorization request
Store it in the user’s session
Verify it matches when receiving the callback
This prevents CSRF attacks

Request minimum scopes

Only request permissions you actually need
Users are more likely to approve limited access
Reduces damage if tokens are compromised

Testing

Use personal tokens for development:

# Export your token
export LICHESS_TOKEN="lip_xxxxxxxxxxxxx"

# Test API access
curl https://lichess.org/api/account \
  -H "Authorization: Bearer $LICHESS_TOKEN"

Common Errors

Error	Solution
`401 Unauthorized`	Token is missing, invalid, or expired
`403 Forbidden`	Token lacks required scope for this endpoint
`Invalid redirect_uri`	Redirect URI doesn’t match registered value
`Invalid client credentials`	Wrong client ID or secret

Next Steps

API Overview

Learn about API structure and response formats

Rate Limits

Understand rate limiting policies

Bot API

Build a chess bot with OAuth

User Profile

Fetch authenticated user data

Getting Started

Games

Users

Tournaments

Studies

Puzzles

Broadcasts

TV & Streaming

Bot API

Overview

Creating an OAuth App

OAuth Scopes

Authorization Code Flow

Personal API Tokens

Using Access Tokens

Token Expiration

Revoking Tokens

Security Best Practices

Testing

Common Errors

Next Steps

API Overview

Rate Limits

Bot API

User Profile

​Overview

​Creating an OAuth App

​OAuth Scopes

​Authorization Code Flow

​Personal API Tokens

​Using Access Tokens

​Token Expiration

​Revoking Tokens

​Security Best Practices

​Testing

​Common Errors

​Next Steps

API Overview

Rate Limits

Bot API

User Profile

Overview

Creating an OAuth App

OAuth Scopes

Authorization Code Flow

Personal API Tokens

Using Access Tokens

Token Expiration

Revoking Tokens

Security Best Practices

Testing

Common Errors

Next Steps