> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.wynncraft.com/oauth2/authorizing-an-application/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.wynncraft.com/_mcp/server.

# Authorizing an application

## Before you start

Before authorizing a user, you need to create an application and set

* at least one `redirect_uri`
* the scopes you want to request

See [Creating an application](/oauth2/creating-an-application) for applications setup.

## Using the generated authorization URL

The application editor includes a URL generator. It builds an authorization URL from:

* your application ID
* the selected redirect URI
* the scopes enabled for the application

Open that generated URL in the user browser to start the authorization.

> **Warning**
>
> You must add an additional parameter to the url generated: `state`, it's a value you define yourself that you can use to properly authenticate users being redirected to your application after a sucessful authorization.

## Scopes

The authorization request only grants access to the scopes your application requests and the user approves.

The currently exposed scopes are:

* `identify`
* `main_access`
* `character_list_access`
* `character_data_access`
* `character_build_access`
* `online_status`
* `hunted_characters_access`
* `guild_history_access`
* `guild_high_ranked_access`

Only request the scopes your application needs.

# Access Token Generation

## Authorization Code

After a user authorizes your application, they will be redirected to the `redirect_uri` you provided in the authorization url,
that redirect will also cary two query parameters, `code` and `state`.

* `code` is the Authorization code, you will need to provide it to [POST /oauth/token](https://docs.wynncraft.com/modules/o-auth-2/exchange-oauth-token) to generate an access token
* `state` is the initial untouched value you added to the authorization url, used to determine who has authorized your app

> **Note**
>
> Authorization codes are one-time use and expire after 5 minutes.

## Public applications and PKCE

Public applications must use PKCE.

Wynncraft only supports the `S256` PKCE method.

For public applications:

* generate a `code_verifier`
* encore and hash `code_verifier` to get your `code_challenge` using `S256`
* include the `code_challenge` and `code_challenge_method` (must be `S256`) values in the authorization url
* keep the `code_verifier` for later, you will need it to generate an access token using [POST /oauth/token](https://docs.wynncraft.com/modules/o-auth-2/exchange-oauth-token)

You can use PKCE for a private application, but it is optional as private applications rely on their `client_secret`.

## Private applications

For Private applications:

* authorize the user
* provide the application's `client_secret` on [POST /oauth/token](https://docs.wynncraft.com/modules/o-auth-2/exchange-oauth-token) to retrieve an access token

## Note

If an error occurs during the authorization, the user will be redirected to your `redirect_uri` alongside query parameters:

* `error`
* `error_description`
* `state`

> Authorize your application and retrieve an access token