---
title: "Request authorization code"
method: GET
path: "/oauth"
tags: ["OAuth"]
---

# Request authorization code

`GET /oauth`

OAuth2 authorization endpoint.
Start the OAuth2 Authorization Code Flow with PKCE by securely
generating two random strings unique to each authorization
request:

* `code_verifier`
* `state`

Store these in session storage. Make sure not to reveal `code_verifier`
to eavesdroppers. Do not show it in URLs, do not abuse `state` to store
it, do not send it over insecure connections. However it is fine if
the user themselves can extract `code_verifier`, which will always be
possible for fully client-side apps.
Then send the user to this endpoint. They will be prompted to grant
authorization and then be redirected back to the given `redirect_uri`.
If the authorization failed, the following query string parameters will
be appended to the redirection:

* `error`, in particular with value `access_denied` if the user
   cancelled authorization
* `error_description` to aid debugging
* `state`, exactly as passed in the `state` parameter

If the authorization succeeded, the following query string parameters
will be appended to the redirection:

* `code`, containing a fresh short-lived authorization code
* `state`, exactly as passed in the `state` parameter

Next, to defend against cross site request forgery, check that the
returned `state` matches the `state` you originally generated.

Finally, continue by using the authorization code to
[obtain an access token](#tag/oauth/POST/api/token).

## Query parameters

- `response_type` 'code', required
- `client_id` string, required
- `redirect_uri` string, required
- `code_challenge_method` 'S256', required
- `code_challenge` string, required
- `scope` string
- `username` string
- `state` string

## Response `200`

Authorization prompt will be displayed to the user.

---

[API](https://skmtc.net/lichess/apis/lichess-org-api-reference.md) · [All operations](https://skmtc.net/lichess/apis/lichess-org-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lichess/lichess-org-api-reference/versions/1425db81eb3b/schema)