v3.5 - User System | Wynncraft

v3.5 is mostly an internal platform update. Response skeletons are mostly similar, but users, developer tokens, privacy rules, per-user cache, and the new throttling system were added.

Authentication and users

See Authentication for the current authentication guide.

Added user accounts.
Added TOTP-based two-factor authentication.
Added token authentication through Authorization: Bearer <token>.
Added public tokens. Public tokens still use the token owner’s user cache and throttling identity, but requests behave like anonymous requests and do not bypass privacy settings.
Added per-user cache.
Added per-module throttling.
Added higher request limits for authenticated users.
Added theming.
Added Discord linking.
Added multiple Minecraft account linking and primary-account selection.
Added limited data request support.
Added privacy options controlling player stats route behavior.

OAuth2 is not included in this initial release, but it is planned for a future patch.

Response headers

Ratelimit-Bucket > The bucket the request belongs to.
Ratelimit-Limit > Requests allowed per minute for the current bucket.
Ratelimit-Reset > Remaining time before the current request cycle resets.
UserID > Authenticated user ID.
UserType > Authenticated user type, such as SESSION or TOKEN.
Cache-Source > User or Shared.

User cache is shared between session and token requests for the same user, except when using a public token.

Throttling

Initial throttling buckets:

SHARED: 50 RPM guest / 120 RPM authenticated.
PLAYER: 50 RPM guest / 120 RPM authenticated.
GUILD: 50 RPM guest / 120 RPM authenticated.
ITEMS: 50 RPM guest / 120 RPM authenticated.
LEADERBOARDS: 50 RPM guest / 120 RPM authenticated.
MAP: 50 RPM guest / 120 RPM authenticated.

Buckets are tracked independently. For example, using both the PLAYER and GUILD buckets gives each bucket its own request budget.

Authentication limitations:

Unlocking tokens requires at least one linked Minecraft account.
Accounts without a linked Minecraft account do not receive raised throttling rates.

Player profile and character endpoints

GET /player/{username}

Added restrictions to responses affected by privacy rules.
Added featuredStats, containing the five stats chosen by the player.
featuredStats is empty when the player has hidden main stats.
Online status privacy removes the player from the online player list, but still counts them in the total online player count.

GET /player/{username}/characters/{uuid}

Added configurable character skeleton output.
Character skeleton customization can remove individual stats from character data while keeping them in global data.
Added removedStat, listing stats removed from the character skeleton.

Leaderboards

GET /leaderboards/{lb_type}

Added leaderboard opt-out.
Opting out takes effect after the next leaderboard computation, usually within roughly 10 minutes.
Opting out anonymizes leaderboard entries instead of deleting scores.

Item endpoints

GET /item/database and POST /item/search

Fixed an issue where items could be skipped in pagination.
Changed pagination controller format.
Requests above the maximum page now return the last page instead of failing unexpectedly.

Controller format:

{
  "controller": {
    "count": 5442,
    "current_count": 20,
    "pages": 273,
    "prev": null,
    "current": 1,
    "next": 2
  }
}

An advanced search endpoint with modular filters and operators such as equality, greater-than, less-than, and ranges was started but not included in this release.

Error handling

Error responses now use a structured format:

{
  "error": "ErrorName",
  "detail": "Error description",
  "code": 400
}

Multiple selectors follow the same structure:

{
  "error": "MultipleObjectsReturned",
  "detail": "Query returned multiple results.",
  "code": 300,
  "objects": {
    "1ed075fc-5aa9-42e0-a29f-640326c1d80c": {
      "username": "Nepmia",
      "rank": "Owner",
      "supportRank": "hero",
      "shortenedRank": "Owner",
      "legacyRankColour": {
        "main": "#aa0000",
        "sub": "#ff5555"
      },
      "rankBadge": "nextgen/badges/rank_owner.svg"
    },
    "98bc2236-ada5-4039-b560-8aaa4cc50384": {
      "username": "nepmia",
      "rank": "Administrator",
      "supportRank": null,
      "shortenedRank": "Admin",
      "legacyRankColour": {
        "main": "#aa0000",
        "sub": "#ff5555"
      },
      "rankBadge": "nextgen/badges/rank_administrator.svg"
    }
  }
}

See Exceptions for the current exception reference.

Related endpoints