Access requests
To see a player's private accounts, an application asks the player for access. The player reviews what the application asks for on MinecraftAuth.me and approves or denies it.
You'll need an application first: create one on the Developers page. There are two ways to ask:
| Use it when | |
|---|---|
| Redirect | you run a website that can receive the player afterwards. Register its redirect URLs on your application. |
| Request codes | there's no website to send the player back to: a Discord bot, a Minecraft plugin, a CLI, or a static site hosted elsewhere. Redirect URLs aren't needed. |
Either way, the player approves on the same screen, and the result is the same signed token and the same stored approval. If you only need to know who the player is right now, such as to sign them in to your site, ask for a one-off check instead, and nothing is stored.
Redirect#
1. Send the player to /grant#
https://minecraftauth.me/grant?app=<applicationId>&state=<state>&redirectUrl=<url>&scopes=<platforms>
| Parameter | |
|---|---|
app |
your application ID |
state |
an unguessable value you generate per request and check when the player returns (CSRF protection) |
redirectUrl |
where to send the player afterwards; must start with one of your application's registered redirect URLs |
scopes |
space-separated platform ids, e.g. minecraft discord |
persist |
optional; false makes this a one-off check |
If the player isn't signed in or hasn't linked a requested platform, the page lets them link it first. Platforms the player set to Hint or Hidden are flagged on the page, so they know approving shares them anyway.
2. Handle the redirect#
Denied:
<redirectUrl>?status=canceled&state=<state>
Approved:
<redirectUrl>?status=accepted&token=<jwt>&state=<state>
Verify the token before trusting it, since it came through the player's browser.
Request codes#
Your application starts the request itself and gets back a link and a short code. The player opens the link, or types the code at https://minecraftauth.me/grant, and approves. Your application polls until the player answers. Both calls need your application credentials, so make them from your bot, plugin or server, never from a browser.
1. Start a request#
curl -A "MyBot/1.0" -u "<applicationId>:<secret>" \
-H "Content-Type: application/json" -d '{"scopes": ["minecraft", "discord"]}' \
https://minecraftauth.me/api/v2/grant-requestsval credentials = Base64.getEncoder().encodeToString("$applicationId:$secret".toByteArray())
val request = HttpRequest.newBuilder(URI("https://minecraftauth.me/api/v2/grant-requests"))
.header("User-Agent", "MyBot/1.0")
.header("Authorization", "Basic $credentials")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("""{"scopes": ["minecraft", "discord"]}"""))
.build()
val response = client.send(request, HttpResponse.BodyHandlers.ofString())
val grant = JsonParser.parseString(response.body()).asJsonObjectconst credentials = btoa(`${applicationId}:${secret}`);
const response = await fetch("https://minecraftauth.me/api/v2/grant-requests", {
method: "POST",
headers: {
"User-Agent": "MyBot/1.0",
Authorization: `Basic ${credentials}`,
"Content-Type": "application/json",
},
body: JSON.stringify({scopes: ["minecraft", "discord"]}),
});
const {id, url, code, interval} = await response.json();req, _ := http.NewRequest("POST", "https://minecraftauth.me/api/v2/grant-requests",
strings.NewReader(`{"scopes": ["minecraft", "discord"]}`))
req.Header.Set("User-Agent", "MyBot/1.0")
req.Header.Set("Content-Type", "application/json")
req.SetBasicAuth(applicationID, secret)
resp, err := http.DefaultClient.Do(req)
if err != nil {
return err
}
defer resp.Body.Close()
var grant struct {
ID string `json:"id"`
Code string `json:"code"`
URL string `json:"url"`
Interval int `json:"interval"`
}
err = json.NewDecoder(resp.Body).Decode(&grant)scopes is a list of platform ids. minecraft is always included, and leaving scopes out (or sending no body)
asks for Minecraft alone. Add "persist": false to make it a one-off check. Response,
201 Created:
{
"id": "q8Zf2kLx0aBcDeFgHiJkLmNoPqRsTuVw",
"code": "HXRW-4KTM",
"url": "https://minecraftauth.me/grant?code=HXRW-4KTM",
"verificationUrl": "https://minecraftauth.me/grant",
"scopes": ["minecraft", "discord"],
"persist": true,
"expiresAt": 1795319692000,
"interval": 5
}
| Field | |
|---|---|
id |
the request's ID, for polling. Keep it to yourself. |
code |
what the player enters at verificationUrl. It works once. |
url |
a link that opens the request directly, with the code filled in |
verificationUrl |
where the player can type the code, for when a link can't be clicked |
persist |
whether approving stores the approval, as you asked |
expiresAt |
when the player can no longer answer (epoch ms), 10 minutes from now |
interval |
how many seconds to wait between polls |
Show the player url, for example as a clickable chat message or a button, or tell them to enter code at
verificationUrl. An application can have at most 100 unanswered requests at once. Past that, starting another
returns 429.
2. Poll for the answer#
curl -A "MyBot/1.0" -u "<applicationId>:<secret>" https://minecraftauth.me/api/v2/grant-requests/<id>// grant and credentials are from the previous step. This blocks, so run it off the server thread.
val id = grant["id"].asString
val interval = grant["interval"].asLong
while (true) {
Thread.sleep(interval * 1000)
val request = HttpRequest.newBuilder(URI("https://minecraftauth.me/api/v2/grant-requests/$id"))
.header("User-Agent", "MyBot/1.0")
.header("Authorization", "Basic $credentials")
.build()
val response = client.send(request, HttpResponse.BodyHandlers.ofString())
if (response.statusCode() != 200) throw IOException("Polling failed: ${response.body()}")
val answer = JsonParser.parseString(response.body()).asJsonObject
when (answer["status"].asString) {
"pending" -> continue
"accepted" -> return answer["token"].asString
else -> return null // denied or expired
}
}// id, interval and credentials are from the previous step
while (true) {
await new Promise((resolve) => setTimeout(resolve, interval * 1000));
const response = await fetch(`https://minecraftauth.me/api/v2/grant-requests/${id}`, {
headers: {"User-Agent": "MyBot/1.0", Authorization: `Basic ${credentials}`},
});
if (!response.ok) throw new Error(`Polling failed: ${await response.text()}`);
const {status, token} = await response.json();
if (status === "accepted") return token as string;
if (status !== "pending") return null; // denied or expired
}// grant is from the previous step
for {
time.Sleep(time.Duration(grant.Interval) * time.Second)
req, _ := http.NewRequest("GET", "https://minecraftauth.me/api/v2/grant-requests/"+grant.ID, nil)
req.Header.Set("User-Agent", "MyBot/1.0")
req.SetBasicAuth(applicationID, secret)
resp, err := http.DefaultClient.Do(req)
if err != nil {
return "", err
}
var answer struct {
Status string `json:"status"`
Token string `json:"token"`
}
if resp.StatusCode != http.StatusOK {
err = fmt.Errorf("polling failed: %s", resp.Status)
} else {
err = json.NewDecoder(resp.Body).Decode(&answer)
}
resp.Body.Close()
if err != nil {
return "", err
}
switch answer.Status {
case "pending":
continue
case "accepted":
return answer.Token, nil
default:
return "", nil // denied or expired
}
}{ "status": "accepted", "expiresAt": 1795319692000, "token": "eyJ..." }
status |
|
|---|---|
pending |
the player hasn't answered yet; poll again after interval seconds |
accepted |
the player approved; token is the token |
denied |
the player denied the request |
expired |
the player didn't answer in time; start a new request if you still need one |
Stop polling once the status isn't pending. Requests are deleted about an hour after they expire, and polling one
after that returns 404. Another application's request IDs also return 404.
Because the token comes straight from MinecraftAuth.me in an authenticated response, you can read its claims without verifying the signature. Verifying it anyway does no harm.
Anyone with the link can answer the request as themselves. If you asked on behalf of a particular player, check the
token's minecraft claim against who you expected, such as the UUID of the player who ran your in-game command.
One-off checks#
By default an approval is stored, and your application keeps seeing the approved accounts through the
API. When you only need the token, such as to sign a player in to your site, pass persist=false (redirect) or
"persist": false (request codes). The player sees that you're asking once, approves the same way, and you get the
same token, but no approval is stored: your application doesn't appear on the player's account page, and lookups
made with your credentials see only what the player's privacy settings show everyone.
A one-off check doesn't touch an approval the player gave you earlier. Anything they already granted stays granted.
In the redirect flow, persist travels through the player's browser like the other parameters, so a player could
remove it. That only stores an approval they agreed to; it doesn't change the token.
The token#
The token is a JWT signed with RS512. Verify it with the public key at
https://minecraftauth.me/rsa (PEM). Its claims:
| Claim | |
|---|---|
sub |
the player's MinecraftAuth.me identity ID (stable; use it as your user key) |
iss |
MinecraftAuth.me |
iat |
when the player approved |
<platform> |
one per approved, linked platform: {"identifier": "...", "name": "...", "avatar": "..."} (name and avatar may be null) |
{
"sub": "1",
"iss": "MinecraftAuth.me",
"iat": 1795319092,
"minecraft": { "identifier": "069a79f4-44e9-4726-a5be-fca90e38aaf5", "name": "Notch", "avatar": "https://crafatar.com/avatars/069a79f444e94726a5befca90e38aaf5?overlay" },
"discord": { "identifier": "111111111111111111", "name": "notch", "avatar": "https://cdn.discordapp.com/avatars/..." }
}
Afterwards#
Unless it was a one-off check, the approval is stored. Lookups and membership checks made with your application credentials include the approved accounts until the player revokes access (on their account page) or unlinks the account. Later approvals add to earlier ones. Don't cache identifiers longer than you need them. Look them up again instead, so a revocation actually reaches your users.