Skip to main content

​
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

1

Register your application

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
2

Get your credentials

After creating the app, you’ll receive:
  • Client ID: Public identifier for your app
  • Client Secret: Keep this confidential!
3

Choose your scopes

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

​
OAuth Scopes

Scopes define what your app can access:
ScopeDescription
preference:readRead user preferences
preference:writeModify user preferences
email:readRead user email address
challenge:readRead incoming challenges
challenge:writeCreate and accept challenges
challenge:bulkCreate bulk pairings (tournaments)
study:readRead private studies
study:writeCreate and modify studies
tournament:writeCreate tournaments
racer:writeCreate puzzle races
puzzle:readRead puzzle activity
team:readRead team information
team:writeManage team memberships
team:leadLead teams (kick members, etc.)
follow:readRead followed players
follow:writeFollow/unfollow players
msg:writeSend direct messages
board:playPlay games via Board API
bot:playPlay games as a bot
engine:readRead engine evaluations
engine:writeRequest engine analysis
web:modModerator 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:
1

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
2

User authorizes your app

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

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.
4

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:
  1. Go to https://lichess.org/account/oauth/token
  2. Select required scopes
  3. Click “Create”
  4. 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"

​
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

  • 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
  • Always use HTTPS for OAuth redirects
  • Never send tokens over unencrypted connections
  • Validate SSL certificates
  • 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
  • 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

ErrorSolution
401 UnauthorizedToken is missing, invalid, or expired
403 ForbiddenToken lacks required scope for this endpoint
Invalid redirect_uriRedirect URI doesn’t match registered value
Invalid client credentialsWrong 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

Build docs developers (and LLMs) love

Get started for freeTalk to us