{ "info": { "_postman_id": "8b579b02-e4db-41a3-8b76-dbba226cf8d2", "name": "Lichess.org API reference Account Messaging API", "description": "# Introduction\nWelcome to the reference for the Lichess API! Lichess is free/libre,\nopen-source chess server powered by volunteers and donations.\n- Get help in the [Lichess Discord channel](https://discord.gg/lichess)\n- API demo app with OAuth2 login and gameplay: [source](https://github.com/lichess-org/api-demo) / [demo](https://lichess-org.github.io/api-demo/)\n- API UI app with OAuth2 login and endpoint forms: [source](https://github.com/lichess-org/api-ui) / [website](https://lichess.org/api/ui)\n- [Contribute to this documentation on Github](https://github.com/lichess-org/api)\n- Check out [Lichess widgets to embed in your website](https://lichess.org/developers)\n- [Download all Lichess rated games](https://database.lichess.org/)\n- [Download all Lichess puzzles with themes, ratings and votes](https://database.lichess.org/#puzzles)\n- [Download all evaluated positions](https://database.lichess.org/#evals)\n\n## Endpoint\nAll requests go to `https://lichess.org` (unless otherwise specified).\n\n## Clients\n- [Python general API](https://github.com/lichess-org/berserk)\n- [MicroPython general API](https://github.com/mkomon/uberserk)\n- [Python general API - async](https://pypi.org/project/async-lichess-sdk)\n- [Python Lichess Bot](https://github.com/lichess-bot-devs/lichess-bot)\n- [Python Board API for Certabo](https://github.com/haklein/certabo-lichess)\n- [Java general API](https://github.com/tors42/chariot)\n- [JavaScript & TypeScript general API](https://github.com/devjiwonchoi/equine)\n- [LichessNET - C# API Wrapper](https://github.com/Rabergsel/LichessNET)\n- [.NET general API](https://github.com/Dblike/LichessSharp)\n\n## Rate limiting\nAll requests are rate limited using various strategies,\nto ensure the API remains responsive for everyone.\nOnly make one request at a time.\nIf you receive an HTTP response with a [429 status](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#429),\nyou have exceded one of the rate limits.\nIn most cases, waiting one minute before retrying will be sufficient, but some limits may require longer.\nReduce your request frequency before retrying.\n\n## Streaming with ND-JSON\nSome API endpoints stream their responses as [Newline Delimited JSON a.k.a. **nd-json**](https://github.com/ndjson/ndjson-spec), with one JSON object per line.\n\nHere's a [JavaScript utility function](https://gist.github.com/ornicar/a097406810939cf7be1df8ea30e94f3e) to help reading NDJSON streamed responses.\n\n## Authentication\n### Which authentication method is right for me?\n[Read about the Lichess API authentication methods and code examples](https://github.com/lichess-org/api/blob/master/example/README.md)\n\n### Personal Access Token\nPersonal API access tokens allow you to quickly interact with Lichess API without going through an OAuth flow.\n- [Generate a personal access token](https://lichess.org/account/oauth/token)\n- `curl https://lichess.org/api/account -H \"Authorization: Bearer {token}\"`\n- [NodeJS example](https://github.com/lichess-org/api/tree/master/example/oauth-personal-token)\n\n### Token Security\n- Keep your tokens secret. Do not share them in public repositories or public forums.\n- 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.\n- 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.\n- If you suspect a token has been compromised, revoke it immediately.\n\nTo see your active tokens or revoke them, see [your Personal API access tokens](https://lichess.org/account/oauth/token).\n\n### Authorization Code Flow with PKCE\nThe authorization code flow with PKCE allows your users to **login with Lichess**.\nLichess supports unregistered and public clients (no client authentication, choose any unique client id).\nThe only accepted code challenge method is `S256`.\nAccess tokens are long-lived (expect one year), unless they are revoked.\nRefresh tokens are not supported.\n\nSee the [documentation for the OAuth endpoints](#tag/OAuth) or\nthe [PKCE RFC](https://datatracker.ietf.org/doc/html/rfc7636#section-4) for a precise protocol description.\n\n- [Demo app](https://lichess-org.github.io/api-demo/)\n- [Minimal client-side example](https://github.com/lichess-org/api/tree/master/example/oauth-app)\n- [Flask/Python example](https://github.com/lakinwecker/lichess-oauth-flask)\n- [Java example](https://github.com/tors42/lichess-oauth-pkce-app)\n- [NodeJS Passport strategy to login with Lichess OAuth2](https://www.npmjs.com/package/passport-lichess)\n\n#### Real life examples\n- [PyChess](https://github.com/gbtami/pychess-variants) ([source code](https://github.com/gbtami/pychess-variants))\n- [Lichess4545](https://www.lichess4545.com/) ([source code](https://github.com/cyanfish/heltour))\n- [English Chess Federation](https://ecf.octoknight.com/)\n- [Rotherham Online Chess](https://rotherhamonlinechess.azurewebsites.net/tournaments)\n\n### Token format\nAccess tokens and authorization codes match `^[A-Za-z0-9_]+$`.\nThe length of tokens can be increased without notice. Make sure your application can handle at least 512 characters.\nBy convention tokens have a recognizable prefix, but do not rely on this.\n\n\nContact Support:\n Name: Lichess.org API\n Email: contact@lichess.org", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "createdAt": "2026-07-28T02:06:48.000Z", "updatedAt": "2026-07-28T02:06:48.000Z", "lastUpdatedBy": "35240", "uid": "35240-8b579b02-e4db-41a3-8b76-dbba226cf8d2" }, "item": [ { "name": "inbox", "item": [ { "name": "{username}", "item": [ { "name": "Send a private message", "id": "29ea168f-c8ab-4aa3-981e-205243a9ec54", "protocolProfileBehavior": { "disableBodyPruning": true }, "request": { "auth": { "type": "oauth2", "oauth2": [ { "key": "scope", "value": "preference:read preference:write email:read engine:read engine:write challenge:read challenge:write challenge:bulk study:read study:write tournament:write racer:write puzzle:read puzzle:write team:read team:write team:lead follow:read follow:write msg:write board:play bot:play web:mod", "type": "string" }, { "key": "accessTokenUrl", "value": "https://lichess.org/api/token", "type": "string" }, { "key": "authUrl", "value": "https://lichess.org/oauth", "type": "string" }, { "key": "grant_type", "value": "authorization_code", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" }, { "key": "Accept", "value": "application/json" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "description": "(Required) ", "key": "text", "value": "" } ] }, "url": { "raw": "{{baseUrl}}/inbox/:username", "host": [ "{{baseUrl}}" ], "path": [ "inbox", ":username" ], "variable": [ { "id": "0594f2b9-9a0c-4ea2-864e-85f0dc5885ba", "key": "username", "value": "", "description": "(Required) " } ] }, "description": "Send a private message to another player.\n" }, "response": [ { "id": "605cf710-8456-483e-aaa9-ff8eba637b28", "name": "The private message has been successfully sent.", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" }, { "key": "Accept", "value": "application/json" }, { "description": "Added as a part of security scheme: oauth2", "key": "Authorization", "value": "" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "description": "(Required) ", "key": "text", "value": "" } ] }, "url": { "raw": "{{baseUrl}}/inbox/:username", "host": [ "{{baseUrl}}" ], "path": [ "inbox", ":username" ], "variable": [ { "key": "username" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "responseTime": null, "body": "{\n \"ok\": \"\"\n}", "createdAt": "2026-07-28T02:06:48.000Z", "updatedAt": "2026-07-28T02:06:48.000Z", "uid": "35240-605cf710-8456-483e-aaa9-ff8eba637b28" }, { "id": "b7a98e8a-627f-4669-8400-98820f42ad00", "name": "The sending of the private message has failed.", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" }, { "key": "Accept", "value": "application/json" }, { "description": "Added as a part of security scheme: oauth2", "key": "Authorization", "value": "" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "description": "(Required) ", "key": "text", "value": "" } ] }, "url": { "raw": "{{baseUrl}}/inbox/:username", "host": [ "{{baseUrl}}" ], "path": [ "inbox", ":username" ], "variable": [ { "key": "username" } ] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "responseTime": null, "body": "{\n \"error\": \"\"\n}", "createdAt": "2026-07-28T02:06:48.000Z", "updatedAt": "2026-07-28T02:06:48.000Z", "uid": "35240-b7a98e8a-627f-4669-8400-98820f42ad00" } ], "createdAt": "2026-07-28T02:06:48.000Z", "updatedAt": "2026-07-28T02:06:48.000Z", "uid": "35240-29ea168f-c8ab-4aa3-981e-205243a9ec54" } ], "id": "89da6239-63f1-489f-9e7a-2d0f9a3b1625", "createdAt": "2026-07-28T02:06:48.000Z", "updatedAt": "2026-07-28T02:06:48.000Z", "uid": "35240-89da6239-63f1-489f-9e7a-2d0f9a3b1625" } ], "id": "4aa213f3-ded8-4b58-8c42-42ddb11e0467", "createdAt": "2026-07-28T02:06:48.000Z", "updatedAt": "2026-07-28T02:06:48.000Z", "uid": "35240-4aa213f3-ded8-4b58-8c42-42ddb11e0467" } ], "variable": [ { "key": "baseUrl", "value": "https://lichess.org" } ] }