For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Create tokenDev Discord
  • Get started
    • Introduction
    • Authentication
    • API Privacy
    • Exceptions
    • Dev Discord
      • Creating an application
      • Authorizing an application
      • Use application's access tokens
      • OAuth2 quirks
  • Modules
  • Changelog
    • v3.7.2 - OAuth2
    • v3.7.1
    • v3.7
    • v3.6 - Fruma Expansion
    • v3.5.2
    • v3.5.1
    • v3.5 - User System
    • v3.4
    • v3.3.4
    • v3.3.3
    • v3.3.2
    • v3.3.1
    • v3.3 - Rekindled World
    • v3.2.5
    • v3.2.4
    • v3.2.3
    • v3.2.2
    • v3.2.1
    • v3.2
    • v3.1
    • v3.0
LogoLogoWynncraft API - Documentation
Create tokenDev Discord
On this page
  • Before you start
  • Using the generated authorization URL
  • Scopes
  • Access Token Generation
  • Authorization Code
  • Public applications and PKCE
  • Private applications
  • Note
Get startedOAuth2

Authorizing an application

Authorize your application and retrieve an access token
Was this page helpful?
Edit this page
Previous

Creating an application

Next

Use application's access tokens

Built with

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

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

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

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