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.
subscribedonly takesdata. v1'srole(Discord) andtier(Twitch) aliases are gone.- Platform ids are
minecraft,discord,twitch,patreon,google, case-insensitive. Unknown ids are a400(v1 sometimes answered500). - 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:
- Read
accounts, not the top-level object. - An entry may not have an
identifier.{"hint": true}means "linked, but the player keeps it private". - A missing platform means unlinked, hidden, or not in your
include. Don't treat it as proof the player has no account. - With
include, a visible-nothing result is200 {"accounts": {}}. v1 answered404in 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/tokenworks 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
Authorizationheader it must be valid: v2 answers401/403instead of silently ignoring it. - A missing
User-Agentis still a403.
Handling private accounts#
Players with Hint or Hidden accounts can still use your integration, but you'll need their permission to see those accounts:
- 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. - 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.
- Membership checks keep working for Hint accounts. Hidden accounts answer
404unless the player allowed membership checks for that account, or approved your application for that platform. - 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}answer400instead of500/404. - A membership check for a player who never linked anything answers
{"result": false}without creating an empty identity for them. - Some
exceptionmessages are worded differently (see the table above). Theresultvalues 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();val request = HttpRequest.newBuilder(URI("https://minecraftauth.me/api/lookup?minecraft=$uuid"))
.header("User-Agent", "MyPlugin/1.0")
.build()
val response = client.send(request, HttpResponse.BodyHandlers.ofString())
if (response.statusCode() == 404) return null
val body = JsonParser.parseString(response.body()).asJsonObject
return body.getAsJsonObject("discord")?.get("identifier")?.asStringconst response = await fetch(`https://minecraftauth.me/api/lookup?minecraft=${uuid}`, {
headers: { "User-Agent": "MyPlugin/1.0" },
});
if (response.status === 404) return null;
const body = await response.json();
return body.discord?.identifier ?? null;req, _ := http.NewRequest("GET", "https://minecraftauth.me/api/lookup?minecraft="+uuid, nil)
req.Header.Set("User-Agent", "MyPlugin/1.0")
resp, err := http.DefaultClient.Do(req)
if err != nil {
return "", err
}
defer resp.Body.Close()
if resp.StatusCode == http.StatusNotFound {
return "", nil
}
var body map[string]struct {
Identifier string `json:"identifier"`
}
if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
return "", err
}
return body["discord"].Identifier, nilAfter (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());val request = HttpRequest.newBuilder(
URI("https://minecraftauth.me/api/v2/lookup/minecraft/$uuid?include=discord"))
.header("User-Agent", "MyPlugin/1.0")
.build()
val response = client.send(request, HttpResponse.BodyHandlers.ofString())
when (response.statusCode()) {
200 -> {}
404 -> return DiscordLink.None
else -> throw IOException("MinecraftAuth lookup failed: ${response.body()}")
}
val discord = JsonParser.parseString(response.body()).asJsonObject
.getAsJsonObject("accounts")
.getAsJsonObject("discord")
?: return DiscordLink.None // unlinked or hidden
if (!discord.has("identifier")) return DiscordLink.Hint // linked, but private: ask the player
return DiscordLink.Linked(discord["identifier"].asString)type Account = { identifier: string } | { hint: true };
const response = await fetch(
`https://minecraftauth.me/api/v2/lookup/minecraft/${uuid}?include=discord`,
{ headers: { "User-Agent": "MyPlugin/1.0" } },
);
if (response.status === 404) return { kind: "none" };
if (!response.ok) throw new Error(`MinecraftAuth lookup failed: ${await response.text()}`);
const { accounts } = (await response.json()) as { accounts: Record<string, Account> };
const discord = accounts.discord;
if (!discord) return { kind: "none" }; // unlinked or hidden
if (!("identifier" in discord)) return { kind: "hint" }; // linked, but private: ask the player
return { kind: "linked", id: discord.identifier };req, _ := http.NewRequest("GET", "https://minecraftauth.me/api/v2/lookup/minecraft/"+uuid+"?include=discord", nil)
req.Header.Set("User-Agent", "MyPlugin/1.0")
resp, err := http.DefaultClient.Do(req)
if err != nil {
return DiscordLink{}, err
}
defer resp.Body.Close()
switch resp.StatusCode {
case http.StatusOK:
case http.StatusNotFound:
return DiscordLink{}, nil
default:
msg, _ := io.ReadAll(resp.Body)
return DiscordLink{}, fmt.Errorf("minecraftauth lookup failed: %s", msg)
}
var body struct {
Accounts map[string]struct {
Identifier *string `json:"identifier"`
} `json:"accounts"`
}
if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
return DiscordLink{}, err
}
discord, ok := body.Accounts["discord"]
if !ok {
return DiscordLink{}, nil // unlinked or hidden
}
if discord.Identifier == nil {
return DiscordLink{Hint: true}, nil // linked, but private: ask the player
}
return DiscordLink{ID: *discord.Identifier}, nilMembership 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();// GET /api/subscribed?minecraft=...&platform=twitch&tier=2 with Basic auth
val body = JsonParser.parseString(response.body()).asJsonObject
if (body.has("exception")) log.warn("MinecraftAuth: ${body["exception"].asString}")
return body["result"].asBoolean// GET /api/subscribed?minecraft=...&platform=twitch&tier=2 with Basic auth
const body = await response.json();
if (body.exception) console.warn(`MinecraftAuth: ${body.exception}`);
return body.result as boolean;// GET /api/subscribed?minecraft=...&platform=twitch&tier=2 with Basic auth
var body struct {
Result bool `json:"result"`
Exception string `json:"exception"`
}
if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
return false, err
}
if body.Exception != "" {
log.Printf("MinecraftAuth: %s", body.Exception)
}
return body.Result, nilAfter (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
};// GET /api/v2/subscribed?minecraft=...&platform=twitch&data=2
// with "Authorization: Bearer <token>"
return when (response.statusCode()) {
200 -> JsonParser.parseString(response.body()).asJsonObject["result"].asBoolean
404 -> false // not linked, or private
409, 502 -> throw TemporaryFailure(error(response))
else -> throw ConfigurationError(error(response)) // 400/401/403: tell the server owner
}// GET /api/v2/subscribed?minecraft=...&platform=twitch&data=2
// with "Authorization: Bearer <token>"
switch (response.status) {
case 200:
return ((await response.json()) as { result: boolean }).result;
case 404:
return false; // not linked, or private
case 409:
case 502:
throw new TemporaryFailure(await error(response));
default:
throw new ConfigurationError(await error(response)); // 400/401/403: tell the server owner
}// GET /api/v2/subscribed?minecraft=...&platform=twitch&data=2
// with "Authorization: Bearer <token>"
switch resp.StatusCode {
case http.StatusOK:
var body struct {
Result bool `json:"result"`
}
err := json.NewDecoder(resp.Body).Decode(&body)
return body.Result, err
case http.StatusNotFound:
return false, nil // not linked, or private
case http.StatusConflict, http.StatusBadGateway:
return false, temporaryFailure(resp)
default:
return false, configurationError(resp) // 400/401/403: tell the server owner
}Checklist#
- Replace
/api/...and/api/v1/...URLs with/api/v2/...(see the mapping). -
youtubebecomesgoogle;role/tierbecomedata. - Parse lookups from
accounts, and handle entries withoutidentifier(hints). - Don't treat a missing platform as "has no account".
- Replace
result/exceptionparsing with HTTP status handling. - Keep sending a
User-Agent. Optionally switch the server token toBearer. - If you need private accounts, create an application on the Developers page and implement the access request flow.
- Check your logs for
Deprecationresponses to confirm nothing still calls v1.