MinecraftAuth.me

API documentation

Contents: Access requests

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-requests

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>
{ "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.