Get startedOAuth2

Authorizing an application

Authorize your application and retrieve an access token

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