MinecraftAuth.me

API documentation

Contents: Migrating to the v2 API

Migrating to the v2 API

This guide covers everything that changes when you move an integration from the original MinecraftAuth.me API (/api/... or /api/v1/...) to v2 (/api/v2/...). The full v2 reference starts at the overview.

Why migrate, and by when#

Players can now choose how visible each linked account is: Public, Hint (others see that the platform is linked, but not the account) or Hidden. They can also approve individual applications to see private accounts. See Privacy.

v1 was designed when every linked account was public. To give integrations time to update, v1 has a 90-day grace period:

During the grace period After the grace period
v2 applies privacy settings applies privacy settings
v1 and unversioned /api/... ignores privacy settings and shows every linked account, as before applies privacy settings: Hint and Hidden accounts are left out of lookups and can't be looked up by; Hidden accounts answer membership checks with false unless the player allows them

Every v1 response carries the exact end date in its Sunset header:

curl -sI -A "MyPlugin/1.0" "https://minecraftauth.me/api/lookup?minecraft=069a79f4-44e9-4726-a5be-fca90e38aaf5" | grep -i sunset
# Sunset: Sat, 20 Feb 2027 03:44:22 GMT

After that date v1 keeps working, but with less data and no way to express a hint. v1 is deprecated and only v2 gets new features, so migrate before then.

Every v1 response also includes headers that help you find what to change:

Deprecation: true
Link: </api/v2/lookup/minecraft/069a79f4-44e9-4726-a5be-fca90e38aaf5>; rel="successor-version", <https://minecraftauth.me/developers/docs/migrating-to-v2>; rel="deprecation"
Sunset: Sat, 20 Feb 2027 03:44:22 GMT

The successor-version link is the v2 equivalent of the exact request you made. Logging it is a quick way to find every call site.

Endpoint mapping#

v1 (and unversioned) v2
GET /api/lookup?minecraft={uuid} GET /api/v2/lookup/minecraft/{uuid}
GET /api/lookup?discord={id} GET /api/v2/lookup/discord/{id}
GET /api/lookup?twitch={id} GET /api/v2/lookup/twitch/{id}
GET /api/lookup?patreon={id} GET /api/v2/lookup/patreon/{id}
GET /api/lookup?youtube={id} GET /api/v2/lookup/google/{id} (the platform id is google everywhere in v2)
GET /api/lookup/{platform}?minecraft={uuid} GET /api/v2/lookup/minecraft/{uuid}?include={platform}
GET /api/following?minecraft=&platform= GET /api/v2/following?minecraft=&platform=
GET /api/subscribed?minecraft=&platform=&role= GET /api/v2/subscribed?minecraft=&platform=&data=
GET /api/subscribed?minecraft=&platform=&tier= GET /api/v2/subscribed?minecraft=&platform=&data=
GET /api/discord/present?minecraft=&server= GET /api/v2/discord/present?minecraft=&server=
GET /api/token unchanged, not versioned (it's part of the website)

Parameter changes:

  • Lookups take the platform and identifier in the path instead of five alternative query parameters. v1 used whichever parameter came first in a fixed order; v2 is explicit.
  • subscribed only takes data. v1's role (Discord) and tier (Twitch) aliases are gone.
  • Platform ids are minecraft, discord, twitch, patreon, google, case-insensitive. Unknown ids are a 400 (v1 sometimes answered 500).
  • Minecraft UUIDs are accepted with or without dashes.

Response changes#

Lookups#

v1 returned the platforms at the top level:

{
  "minecraft": { "identifier": "069a79f4-44e9-4726-a5be-fca90e38aaf5" },
  "discord": { "identifier": "111111111111111111" },
  "twitch": { "identifier": "12345" }
}

v2 wraps them in accounts, and an entry is either an identifier or a hint:

{
  "accounts": {
    "minecraft": { "identifier": "069a79f4-44e9-4726-a5be-fca90e38aaf5" },
    "twitch": { "hint": true }
  }
}

Update your parsing:

  1. Read accounts, not the top-level object.
  2. An entry may not have an identifier. {"hint": true} means "linked, but the player keeps it private".
  3. A missing platform means unlinked, hidden, or not in your include. Don't treat it as proof the player has no account.
  4. With include, a visible-nothing result is 200 {"accounts": {}}. v1 answered 404 in this case.

Membership checks#

v1 returned 200 for almost everything and put failures in the body:

{ "result": false, "exception": "Minecraft Authentication bot not in target server" }

v2 returns {"result": true|false} only when the check actually ran. Everything else is an HTTP error with a {"error": "...", "status": n} body. Stop reading exception, and handle statuses instead:

v1 response v2 status
{"result": false}: player not linked to MinecraftAuth.me at all 404 No identity is linked to that Minecraft account
{"result": false}: player has no account on that platform 404 The target has no linked … account
exception: "Target doesn't have a linked Discord account" 404
exception: "Invalid server ID" 400
exception: "Malformed sub tier level" 400
exception: "Minecraft Authentication bot not in target server" 409
exception: "Server token doesn't have a linked Discord account" 403 The caller has no linked Discord account
exception: "Server token is not present in target Discord server" 403 The caller is not a member of the target Discord server
exception: "Server token is not privileged in target Discord server" 403 The caller is not a moderator of the target Discord server
{"result": false}: the caller (creator) has no account on that platform 403 The caller has no linked … account
exception: "Bad response from Twitch … API" and other platform failures 502 (retry later)
403 No Authorization header set 401

Good practice: treat 404 as "not a member" when gating access, 401/403/400 as configuration errors to report to the server owner, and 409/502 as temporary failures (fail open or closed as suits your use).

Authentication changes#

  • The server token from /api/token works unchanged: Authorization: Basic base64(uid:token).
  • v2 also accepts the bare token: Authorization: Bearer <token> (the part after : in the decoded value).
  • v2 accepts application credentials, Authorization: Basic base64(applicationId:secret), which unlock what players granted your application. See Authentication.
  • Lookups still work anonymously. If you send an Authorization header it must be valid: v2 answers 401/403 instead of silently ignoring it.
  • A missing User-Agent is still a 403.

Handling private accounts#

Players with Hint or Hidden accounts can still use your integration, but you'll need their permission to see those accounts:

  1. Anonymous or server-token lookups show Hint accounts as {"hint": true}. Tell the player what you need, for example "Link your Discord account and approve access so we can give you your role", instead of assuming they have no account.
  2. To see a private account, create an application on the Developers page and send the player through an access request. After they approve, lookups made with your application credentials return the approved accounts.
  3. Membership checks keep working for Hint accounts. Hidden accounts answer 404 unless the player allowed membership checks for that account, or approved your application for that platform.
  4. Don't store more than you need. Look identifiers up again instead of caching them for a long time. Players can revoke access at any time and expect it to take effect.

Things that also changed in v1#

Most v1 behavior is unchanged. These differences were fixed in place, so you may notice them before migrating:

  • Malformed input to /api/lookup (an invalid UUID, a non-numeric Patreon or Twitch ID) and unknown platforms in /api/lookup/{platform} answer 400 instead of 500/404.
  • A membership check for a player who never linked anything answers {"result": false} without creating an empty identity for them.
  • Some exception messages are worded differently (see the table above). The result values are the same.
  • After the grace period, privacy settings apply as described above.

Example code#

Before (v1):

HttpRequest request = HttpRequest.newBuilder(URI.create(
                "https://minecraftauth.me/api/lookup?minecraft=" + uuid))
        .header("User-Agent", "MyPlugin/1.0")
        .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() == 404) return Optional.empty();
JsonObject body = JsonParser.parseString(response.body()).getAsJsonObject();
JsonObject discord = body.getAsJsonObject("discord");
return discord != null ? Optional.of(discord.get("identifier").getAsString()) : Optional.empty();

After (v2):

HttpRequest request = HttpRequest.newBuilder(URI.create(
                "https://minecraftauth.me/api/v2/lookup/minecraft/" + uuid + "?include=discord"))
        .header("User-Agent", "MyPlugin/1.0")
        .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
switch (response.statusCode()) {
    case 200 -> {}
    case 404 -> { return DiscordLink.none(); }
    default -> throw new IOException("MinecraftAuth lookup failed: " + response.body());
}
JsonObject discord = JsonParser.parseString(response.body()).getAsJsonObject()
        .getAsJsonObject("accounts")
        .getAsJsonObject("discord");
if (discord == null) return DiscordLink.none();                                  // unlinked or hidden
if (!discord.has("identifier")) return DiscordLink.hint();                       // linked, but private: ask the player
return DiscordLink.of(discord.get("identifier").getAsString());

Membership check, before (v1):

// GET /api/subscribed?minecraft=...&platform=twitch&tier=2 with Basic auth
JsonObject body = JsonParser.parseString(response.body()).getAsJsonObject();
if (body.has("exception")) log.warn("MinecraftAuth: " + body.get("exception").getAsString());
return body.get("result").getAsBoolean();

After (v2):

// GET /api/v2/subscribed?minecraft=...&platform=twitch&data=2
// with "Authorization: Bearer <token>"
return switch (response.statusCode()) {
    case 200 -> JsonParser.parseString(response.body()).getAsJsonObject().get("result").getAsBoolean();
    case 404 -> false;                                  // not linked, or private
    case 409, 502 -> throw new TemporaryFailure(error(response));
    default -> throw new ConfigurationError(error(response)); // 400/401/403: tell the server owner
};

Checklist#

  • Replace /api/... and /api/v1/... URLs with /api/v2/... (see the mapping).
  • youtube becomes google; role/tier become data.
  • Parse lookups from accounts, and handle entries without identifier (hints).
  • Don't treat a missing platform as "has no account".
  • Replace result/exception parsing with HTTP status handling.
  • Keep sending a User-Agent. Optionally switch the server token to Bearer.
  • If you need private accounts, create an application on the Developers page and implement the access request flow.
  • Check your logs for Deprecation responses to confirm nothing still calls v1.