Get started

Authentication

Token and OAuth2 authentication behavior

Since August 2025, Wynncraft Accounts introduced API features for authenticated users, including user-based caching and authenticated throttling.

The authentication system currently supports three user types:

TypeDescription
SESSIONWynncraft website session-cookie authentication. This is not intended for third-party applications.
TOKENThird-party-friendly authentication using an API token and the Authorization header.
OAUTHOAuth2 application authentication using a bearer token tied to one user and one client.

OAuth2 Clients

OAuth2 clients are intended for applications acting on behalf of a Wynncraft user.

Use OAuth2 when your application needs a user-granted identity and access context.

Current OAuth2 endpoints are under /v3/oauth/*.

  • POST /oauth/token exchanges an authorization code for an access token.
  • GET /oauth/me returns the OAuth2-authenticated application and profile context.

Creating Tokens

You can create up to 3 authentication tokens from your Account Dashboard.

Each token is independent. For example, 3 tokens give each token its own authenticated rate limit per bucket.

When creating a token, provide:

  • A name. This cannot be changed later.
  • A description.

The token value is only shown once during creation. Store it securely.

Public Tokens

Tokens can be set to Public Mode.

A public token:

  • Acts as an authenticated guest.
  • Hides your personal data and stats unless you made them public.
  • Is recommended for public applications.

Use this mode when a token is used by public commands to avoid potential privacy leaks.

Token Deletion

You may delete one token every 2 minutes. This prevents deletion abuse to bypass rate limits.

Token creation is not rate-limited.

Authenticating Requests

Authenticated requests use the Authorization header:

1Authorization: Bearer <token-or-access-token>

Never share account tokens or OAuth2 access tokens with anyone.