Difference between revisions of "Authentication"

From wiki.vg
Jump to navigation Jump to search
m
(Added a new error I've got, if really needed I can provide some screnshots of it)
 
(55 intermediate revisions by 34 users not shown)
Line 1: Line 1:
The minecraft client and server communicate with Mojang to validate player sessions. This page describes some of the operations.
+
Minecraft 1.6 introduced a new authentication scheme called '''Yggdrasil''' which completely replaces the [[Legacy Authentication|previous authentication system]]. Mojang's other game, Scrolls, uses this method of authentication as well. Mojang has said that [https://twitter.com/KrisJelbring/status/453573406341206016 this authentication system should be used by everyone for custom logins], but [https://twitter.com/KrisJelbring/status/461390585086361600 credentials should never be collected from users].  For newer Microsoft accounts, see [[Microsoft Authentication Scheme]].
  
== Authentication ==
+
== Request format ==
 
 
Minecraft 1.6 introduced a new authentication scheme called Yggdrasil which completely replaces the [[Legacy_Authentication|previous authentication system]].
 
 
 
=== Request format ===
 
  
 
All requests to Yggdrasil are made to the following server:
 
All requests to Yggdrasil are made to the following server:
  
  https://authserver.mojang.com
+
https://authserver.mojang.com
  
 
Further, they are expected to fulfill the following rules:
 
Further, they are expected to fulfill the following rules:
Line 15: Line 11:
 
* Are <code>POST</code> requests
 
* Are <code>POST</code> requests
 
* Have the <code>Content-Type</code> header set to <code>application/json</code>
 
* Have the <code>Content-Type</code> header set to <code>application/json</code>
* Contain a [http://json.org JSON]-encoded dictionary as payload
+
* Contain a [[wikipedia:JSON|JSON]]-encoded dictionary as payload
  
 
If a request was successful the server will respond with:
 
If a request was successful the server will respond with:
  
* Status code <code>200</code>
+
* A successful status code <code>2XX</code>
* A [http://json.org JSON]-encoded dictionary according to the specifications below
+
* An empty payload or a [[wikipedia:JSON|JSON]]-encoded dictionary according to the specifications below
  
 
If however a request fails, the server will respond with:
 
If however a request fails, the server will respond with:
  
* An appropriate, non-200 [http://en.wikipedia.org/wiki/List_of_HTTP_status_codes HTTP status code]
+
* An appropriate, non-200 [[wikipedia:List of HTTP status codes|HTTP status code]]
* A [http://json.org JSON]-encoded dictionary following this format:
+
* A [[wikipedia:JSON|JSON]]-encoded dictionary following this format:
 +
 
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "error": "Short description of the error",
+
    "error": "Short description of the error",
  "errorMessage": "Longer description which can be shown to the user",
+
    "errorMessage": "Longer description which can be shown to the user",
  "cause": "Cause of the error"       // optional
+
    "cause": "Cause of the error" // optional
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
=== Session ID ===
+
== Errors ==
 +
 
 +
These are some of the errors that can be encountered:
  
Whenever a Mojang service requires a session ID, you can simply combine a valid <code>accessToken</code> with a profile identifier as follows:
+
{| class="wikitable"
 +
|-
 +
! Error
 +
! Cause
 +
! Error message
 +
! Notes
 +
|-
 +
| <code>Method Not Allowed</code>
 +
|
 +
| The method specified in the request is not allowed for the resource identified by the request URI
 +
| Something other than a POST request was received.
 +
|-
 +
| <code>Not Found</code>
 +
|
 +
| The server has not found anything matching the request URI
 +
| Non-existing endpoint was called.
 +
|-
 +
| <code>ForbiddenOperationException</code>
 +
| <code>UserMigratedException</code>
 +
| Invalid credentials. Account migrated, use email as username.
 +
|
 +
|-
 +
| <code>ForbiddenOperationException</code>
 +
|
 +
| Invalid credentials. Invalid username or password.
 +
|
 +
|-
 +
| <code>ForbiddenOperationException</code>
 +
|
 +
| Invalid credentials.
 +
| Too many login attempts with this username recently (see <code>/authenticate</code>). Note that username and password may still be valid!
 +
|-
 +
| <code>ForbiddenOperationException</code>
 +
|
 +
| Invalid token.
 +
| <code>accessToken</code> was invalid.
 +
|-
 +
| <code>ForbiddenOperationException</code>
 +
|
 +
| Token does not exist.
 +
| <code>accessToken</code> was used in another session that was issued AFTER this session.
 +
|-
 +
| <code>ForbiddenOperationException</code>
 +
|
 +
| Forbidden
 +
| Username/password was not submitted or password is less than 3 characters.
 +
|-
 +
| <code>IllegalArgumentException</code>
 +
|
 +
| Access token already has a profile assigned.
 +
| Selecting profiles isn't implemented yet.
 +
|-
 +
| <code>IllegalArgumentException</code>
 +
|
 +
| Invalid salt version
 +
| ???
 +
|-
 +
| <code>IllegalArgumentException</code>
 +
|
 +
| Access Token can not be null or empty.
 +
| ???
 +
|-
 +
| <code>Unsupported Media Type</code>
 +
|
 +
| The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method
 +
| Data was not submitted as application/json
 +
|-
 +
| <code>ResourceException</code>
 +
|
 +
| Gone (410) - The requested resource is no longer available at the server and no forwarding address is known
 +
| Account was migrated to Microsoft account
 +
|-
 +
| <code>GoneException</code>
 +
|
 +
| Gone (410) - The requested resource is no longer available at the server and no forwarding address is known
 +
| Account was migrated to a Microsoft account
 +
|}
  
  token:<accessToken>:<profile ID>
+
== Authenticate ==
  
=== Authenticate ===
+
Authenticates a user using their password.
  
Authenticates a user using his password.
+
=== Endpoint ===
  
==== Endpoint ====
+
/authenticate
  /authenticate
+
 
 +
=== Payload ===
  
==== Payload ====
 
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "agent": {                             // optional
+
    "agent": {                             // defaults to Minecraft
    "name": "Minecraft",                 // So far this is the only encountered value
+
        "name": "Minecraft",               // For Mojang's other game Scrolls, "Scrolls" should be used
    "version": 1                         // This number might be increased
+
        "version": 1                       // This number might be increased
                                        // by the vanilla client in the future
+
                                            // by the vanilla client in the future
  },
+
    },
  "username": "mojang account name",     // Can be an email address or player name for
+
    "username": "mojang account name",     // Can be an email address or player name for
                                        // unmigrated accounts
+
                                            // unmigrated accounts
  "password": "mojang account password",
+
    "password": "mojang account password",
  "clientToken": "client identifier"    // optional
+
    "clientToken": "client identifier",     // optional
 +
    "requestUser": true                    // optional; default: false; true adds the user object to the response
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
The <code>clientToken</code> should be a randomly generated identifier and must be identical for each request.
+
The <code>clientToken</code> should be a randomly generated identifier and must be identical for each request. The vanilla launcher generates a random (version 4) UUID on first run and saves it, reusing it for every subsequent request. In case it is omitted the server will generate a random token based on Java's [http://docs.oracle.com/javase/7/docs/api/java/util/UUID.html#toString() <code>UUID.toString()</code>] which should then be stored by the client. This will however also invalidate all previously acquired <code>accessToken</code>s for this user across all clients.
In case it is omitted the server will generate a random token based on Java's [http://docs.oracle.com/javase/7/docs/api/java/util/UUID.html#toString() UUID.toString()] which should then be stored by the client. This will however also invalidate all previously acquired <code>accessToken</code>s for this user across all clients.
 
  
 +
=== Response ===
  
==== Response ====
 
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "accessToken": "random access token", // hexadecimal
+
    "user": {
  "clientToken": "client identifier",   // identical to the one received
+
        "username": "user@email.example", // will be account username for legacy accounts
  "availableProfiles": [                 // only present if the agent field was received
+
        "properties": [
     {
+
            {
      "id": "profile identifier",       // hexadecimal
+
                "name": "preferredLanguage",
      "name": "player name"
+
                "value": "en-us"
 +
            },
 +
            {
 +
                "name": "registrationCountry",
 +
                "value": "country" // 2L country (e.g. US)
 +
            }
 +
        ],
 +
        "id": "hexadecimal string" // This is the remoteID for the user
 +
    },
 +
    "clientToken": "client identifier",
 +
    "accessToken": "random access token", // hexadecimal or JSON-Web-Token (unconfirmed) [The normal accessToken can be found in the payload of the JWT (second by '.' separated part as Base64 encoded JSON object), in key "yggt"]
 +
    "availableProfiles": [
 +
        {
 +
            "name": "player username",
 +
            "id": "hexadecimal string" // UUID of the account
 +
        }
 +
    ],
 +
     "selectedProfile": {
 +
        "name": "player username",
 +
        "id": "hexadecimal string" // UUID of the account
 
     }
 
     }
  ],
 
  "selectedProfile": {                  // only present if the agent field was received
 
    "id": "profile identifier",
 
    "name": "player name"
 
  }
 
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
'''Note:''' If a user wishes to stay logged in on his computer you are strongly advised to store the received <code>accessToken</code> instead of the password itself.
 
  
Currently each account will only have one single profile, multiple profiles per account are however planned in the future.
+
'''Note:''' If a user wishes to stay logged in on their computer you are strongly advised to store the received <code>accessToken</code> instead of the password itself.
  
=== Refresh ===
+
Currently each account will only have one single profile, multiple profiles per account are however planned in the future. If a user attempts to log into a valid Mojang account with no attached Minecraft license, the authentication will be successful, but the response will not contain a <code>selectedProfile</code> field, and the <code>availableProfiles</code> array will be empty.
  
Refreshes a valid <code>accessToken</code>. It can be uses to keep a user logged in between gaming sessions and is preferred over storing the user's password in a file (see [[lastlogin]]).  
+
Some instances in the wild have been observed of Mojang returning a flat <code>null</code> for failed refresh attempts against legacy accounts. It's not clear what the actual error tied to the null response is and it is extremely rare, but implementations should be wary of null output from the response.
  
==== Endpoint ====
+
This endpoint is severely rate-limited: multiple <code>/authenticate</code> requests for the same account in a short amount of time (think 3 requests in a few seconds), even with the correct password, will eventually lead to an <code>Invalid credentials.</code> response. This error clears up a few seconds later.
  /refresh
 
  
==== Payload ====
+
== Refresh ==
 +
 
 +
Refreshes a valid <code>accessToken</code>. It can be used to keep a user logged in between gaming sessions and is preferred over storing the user's password in a file (see [[lastlogin]]).
 +
 
 +
=== Endpoint ===
 +
 
 +
/refresh
 +
 
 +
=== Payload ===
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "accessToken": "valid accessToken",
+
    "accessToken": "valid accessToken",
  "clientToken": "client identifier"     // This needs to be identical to the one used
+
    "clientToken": "client identifier"// This needs to be identical to the one used
 
                                         // to obtain the accessToken in the first place
 
                                         // to obtain the accessToken in the first place
 +
    "selectedProfile": {                // optional; sending it will result in an error
 +
        "id": "profile identifier",      // hexadecimal
 +
        "name": "player name"
 +
    },
 +
    "requestUser": true                  // optional; default: false; true adds the user object to the response
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 105: Line 205:
 
Note: The provided <code>accessToken</code> gets invalidated.
 
Note: The provided <code>accessToken</code> gets invalidated.
  
==== Response ====
+
=== Response ===
 +
 
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "accessToken": "random access token", // hexadecimal
+
    "accessToken": "random access token",     // hexadecimal
  "clientToken": "client identifier",   // identical to the one received
+
    "clientToken": "client identifier",       // identical to the one received
  "selectedProfile": {
+
    "selectedProfile": {
    "id": "profile identifier",         // hexadecimal
+
        "id": "profile identifier",           // hexadecimal
    "name": "player name"
+
        "name": "player name"
   }
+
    },
  }
+
    "user": {                                  // only present if requestUser was true in the request payload
 +
        "username": "user@email.example",      // email for Mojang accounts or account username for legacy Minecraft accounts
 +
        "id": "user identifier",              // hexadecimal
 +
        "properties": [
 +
            {
 +
                "name": "preferredLanguage",   // might not be present for all accounts
 +
                "value": "en"                  // Java locale format (https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#toString--)
 +
            },
 +
            {
 +
                "name": "twitch_access_token", // only present if a twitch account is associated (see https://account.mojang.com/me/settings)
 +
                "value": "twitch oauth token" // OAuth 2.0 Token; alphanumerical; e.g. https://api.twitch.tv/kraken?oauth_token=[...]
 +
                                              // the Twitch API is documented here: https://github.com/justintv/Twitch-API
 +
            }
 +
        ]
 +
    }
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
=== Validate ===
+
== Validate ==
 +
 
 +
Checks if an <code>accessToken</code> is usable for authentication with a Minecraft server. The Minecraft Launcher (as of version 1.6.13) calls this endpoint on startup to verify that its saved token is still usable, and calls <code>/refresh</code> if this returns an error.
 +
 
 +
Note that an <code>accessToken</code> may be unusable for authentication with a Minecraft server, but still be good enough for <code>/refresh</code>. This mainly happens when one has used another client (e.g. played Minecraft on another PC with the same account). It seems only the most recently obtained <code>accessToken</code> for a given account can reliably be used for authentication (the next-to-last token also seems to remain valid, but don't rely on it).
 +
 
 +
<code>/validate</code> may be called with or without a <code>clientToken</code>. If a <code>clientToken</code> is provided, it should match the one used to obtain the <code>accessToken</code>. The Minecraft Launcher does send a <code>clientToken</code> to <code>/validate</code>.
  
Checks if an <code>accessToken</code> is valid.
+
=== Endpoint ===
  
==== Endpoint ====
+
/validate
  /validate
+
 
 +
=== Payload ===
  
==== Payload ====
 
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "accessToken": "valid accessToken",
+
    "accessToken": "valid accessToken",
 +
    "clientToken": "associated clientToken" // optional, see above
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==== Response ====
+
=== Response ===
Unlike most other methods this one will return an empty payload if successful.
+
 
 +
Returns an empty payload (<code>204 No Content</code>) if successful, an error JSON with status <code>403 Forbidden</code> otherwise.
 +
 
 +
== Signout ==
 +
 
 +
Invalidates <code>accessToken</code>s using an account's username and password.
 +
 
 +
=== Endpoint ===
 +
 
 +
/signout
 +
 
 +
=== Payload ===
 +
 
 +
<syntaxhighlight lang="javascript">
 +
{
 +
    "username": "mojang account name",
 +
    "password": "mojang account password"
 +
}
 +
</syntaxhighlight>
 +
 
 +
=== Response ===
 +
 
 +
Returns an empty payload if successful.
 +
 
 +
== Invalidate ==
 +
 
 +
Invalidates <code>accessToken</code>s using a client/access token pair.
 +
 
 +
=== Endpoint ===
 +
 
 +
/invalidate
 +
 
 +
=== Payload ===
 +
 
 +
<syntaxhighlight lang="javascript">
 +
{
 +
    "accessToken": "valid accessToken",
 +
    "clientToken": "client identifier"  // This needs to be identical to the one used
 +
                                        // to obtain the accessToken in the first place
 +
}
 +
</syntaxhighlight>
 +
 
 +
=== Response ===
 +
 
 +
Returns an empty payload if successful.
  
 
== Joining a Server ==
 
== Joining a Server ==
  
See [[Protocol Encryption]] for details on encrypting connections.
+
See [[Protocol Encryption#Authentication]]
 
 
=== Client operation ===
 
  
# Client connects to server
+
== Examples ==
# Client sends a [[Protocol#0x02|0x02 handshake]] containing the current player name
 
# Client receives an [[Protocol#0xFD|0xFD encryption request]] with the server's public key and four verification bytes.
 
# Client generates a symmetric key.
 
# Client sends a HTTP request to
 
#:<pre>http://session.minecraft.net/game/joinserver.jsp?user=<player name>&sessionId=<session id>&serverId=<server hash></pre>
 
#:Note: See the [[#Session ID|Session ID]] section on how the <code>&lt;session id&gt;</code> is generated.
 
#:If the response is '''OK''' then continue, otherwise stop
 
# Client sends [[Protocol#0xFC|0xFC encryption response]] - client encrypts shared secret and verification token with the server's public key
 
# Server checks validity and sends [[Protocol#0xFC|0xFC encryption response]] with two empty arrays
 
# Both sides enable AES/CFB2 encryption using the shared secret generated by the client
 
# Client sends [[Protocol#0xCD|0xCD client status]] with a payload of 0 (ready to spawn)
 
# Server sends [[Protocol#0x01|0x01 login]]
 
# ... receive map chunks, etc...
 
  
=== Server operation ===
+
[https://github.com/iBuyMountainDew/yggdrasil Kotlin] | Full Yggdrasil wrapper in Kotlin.
  
# Server generates a 1024-bit RSA keypair.
+
[https://github.com/Kronos666/mclaunch-util-lib Java] | Legacy full Yggdrasil wrapper in Java.
# ...
 
# Server answers TCP connection request and receives a [[Protocol#0x02|0x02 handshake]] from the client.
 
# Server sends [[Protocol#0xFD|0xFD encryption request]] with its public key and a verification token.
 
# Server receives [[Protocol#0xFC|0xFC encryption response]] from client and decrypts the shared secret.
 
# Server verifies the validity of the verification token. If this isn't verified, it kicks the client.
 
# Server sends a HTTP request to
 
#:<pre>http://session.minecraft.net/game/checkserver.jsp?user=<username>&serverId=<server hash></pre>
 
#:If it returns '''YES''' then the client is authenticated and allowed to join. Otherwise the client will/should be [[Protocol#0xFF|kicked]] with “Failed to verify username!”
 
# Server sends a [[Protocol#0xFC|0xFC encryption response]] packet with two empty arrays.
 
# Both sides enable AES/CFB2 encryption.
 
# Server receives [[Protocol#0xCD|0xCD client status]] with a payload of , indicating "ready to spawn"
 
# Server sends [[Protocol#0x01|0x01 login]]
 
# ... send map chunks, etc...
 
  
 
[[Category:Protocol Details]]
 
[[Category:Protocol Details]]
 
[[Category:Minecraft Modern]]
 
[[Category:Minecraft Modern]]

Latest revision as of 00:44, 3 August 2022

Minecraft 1.6 introduced a new authentication scheme called Yggdrasil which completely replaces the previous authentication system. Mojang's other game, Scrolls, uses this method of authentication as well. Mojang has said that this authentication system should be used by everyone for custom logins, but credentials should never be collected from users. For newer Microsoft accounts, see Microsoft Authentication Scheme.

Request format

All requests to Yggdrasil are made to the following server:

https://authserver.mojang.com

Further, they are expected to fulfill the following rules:

  • Are POST requests
  • Have the Content-Type header set to application/json
  • Contain a JSON-encoded dictionary as payload

If a request was successful the server will respond with:

  • A successful status code 2XX
  • An empty payload or a JSON-encoded dictionary according to the specifications below

If however a request fails, the server will respond with:

{
    "error": "Short description of the error",
    "errorMessage": "Longer description which can be shown to the user",
    "cause": "Cause of the error" // optional
}

Errors

These are some of the errors that can be encountered:

Error Cause Error message Notes
Method Not Allowed The method specified in the request is not allowed for the resource identified by the request URI Something other than a POST request was received.
Not Found The server has not found anything matching the request URI Non-existing endpoint was called.
ForbiddenOperationException UserMigratedException Invalid credentials. Account migrated, use email as username.
ForbiddenOperationException Invalid credentials. Invalid username or password.
ForbiddenOperationException Invalid credentials. Too many login attempts with this username recently (see /authenticate). Note that username and password may still be valid!
ForbiddenOperationException Invalid token. accessToken was invalid.
ForbiddenOperationException Token does not exist. accessToken was used in another session that was issued AFTER this session.
ForbiddenOperationException Forbidden Username/password was not submitted or password is less than 3 characters.
IllegalArgumentException Access token already has a profile assigned. Selecting profiles isn't implemented yet.
IllegalArgumentException Invalid salt version ???
IllegalArgumentException Access Token can not be null or empty. ???
Unsupported Media Type The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method Data was not submitted as application/json
ResourceException Gone (410) - The requested resource is no longer available at the server and no forwarding address is known Account was migrated to Microsoft account
GoneException Gone (410) - The requested resource is no longer available at the server and no forwarding address is known Account was migrated to a Microsoft account

Authenticate

Authenticates a user using their password.

Endpoint

/authenticate

Payload

{
    "agent": {                              // defaults to Minecraft
        "name": "Minecraft",                // For Mojang's other game Scrolls, "Scrolls" should be used
        "version": 1                        // This number might be increased
                                            // by the vanilla client in the future
    },
    "username": "mojang account name",      // Can be an email address or player name for
                                            // unmigrated accounts
    "password": "mojang account password",
    "clientToken": "client identifier",     // optional
    "requestUser": true                     // optional; default: false; true adds the user object to the response
}

The clientToken should be a randomly generated identifier and must be identical for each request. The vanilla launcher generates a random (version 4) UUID on first run and saves it, reusing it for every subsequent request. In case it is omitted the server will generate a random token based on Java's UUID.toString() which should then be stored by the client. This will however also invalidate all previously acquired accessTokens for this user across all clients.

Response

{
    "user": {
        "username": "user@email.example", // will be account username for legacy accounts
        "properties": [
            {
                "name": "preferredLanguage",
                "value": "en-us"
            },
            {
                "name": "registrationCountry",
                "value": "country" // 2L country (e.g. US)
            }
        ],
        "id": "hexadecimal string" // This is the remoteID for the user
    },
    "clientToken": "client identifier",
    "accessToken": "random access token", // hexadecimal or JSON-Web-Token (unconfirmed) [The normal accessToken can be found in the payload of the JWT (second by '.' separated part as Base64 encoded JSON object), in key "yggt"]
    "availableProfiles": [
        {
            "name": "player username",
            "id": "hexadecimal string" // UUID of the account
        }
    ],
    "selectedProfile": {
        "name": "player username",
        "id": "hexadecimal string" // UUID of the account
    }
}

Note: If a user wishes to stay logged in on their computer you are strongly advised to store the received accessToken instead of the password itself.

Currently each account will only have one single profile, multiple profiles per account are however planned in the future. If a user attempts to log into a valid Mojang account with no attached Minecraft license, the authentication will be successful, but the response will not contain a selectedProfile field, and the availableProfiles array will be empty.

Some instances in the wild have been observed of Mojang returning a flat null for failed refresh attempts against legacy accounts. It's not clear what the actual error tied to the null response is and it is extremely rare, but implementations should be wary of null output from the response.

This endpoint is severely rate-limited: multiple /authenticate requests for the same account in a short amount of time (think 3 requests in a few seconds), even with the correct password, will eventually lead to an Invalid credentials. response. This error clears up a few seconds later.

Refresh

Refreshes a valid accessToken. It can be used to keep a user logged in between gaming sessions and is preferred over storing the user's password in a file (see lastlogin).

Endpoint

/refresh

Payload

{
    "accessToken": "valid accessToken",
    "clientToken": "client identifier",  // This needs to be identical to the one used
                                         // to obtain the accessToken in the first place
    "selectedProfile": {                 // optional; sending it will result in an error
        "id": "profile identifier",      // hexadecimal
        "name": "player name"
    },
    "requestUser": true                  // optional; default: false; true adds the user object to the response
}

Note: The provided accessToken gets invalidated.

Response

{
    "accessToken": "random access token",      // hexadecimal
    "clientToken": "client identifier",        // identical to the one received
    "selectedProfile": {
        "id": "profile identifier",            // hexadecimal
        "name": "player name"
    },
    "user": {                                  // only present if requestUser was true in the request payload
        "username": "user@email.example",      // email for Mojang accounts or account username for legacy Minecraft accounts
        "id": "user identifier",               // hexadecimal
        "properties": [
            {
                "name": "preferredLanguage",   // might not be present for all accounts
                "value": "en"                  // Java locale format (https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#toString--)
            },
            {
                "name": "twitch_access_token", // only present if a twitch account is associated (see https://account.mojang.com/me/settings)
                "value": "twitch oauth token"  // OAuth 2.0 Token; alphanumerical; e.g. https://api.twitch.tv/kraken?oauth_token=[...]
                                               // the Twitch API is documented here: https://github.com/justintv/Twitch-API
            }
        ]
    }
}

Validate

Checks if an accessToken is usable for authentication with a Minecraft server. The Minecraft Launcher (as of version 1.6.13) calls this endpoint on startup to verify that its saved token is still usable, and calls /refresh if this returns an error.

Note that an accessToken may be unusable for authentication with a Minecraft server, but still be good enough for /refresh. This mainly happens when one has used another client (e.g. played Minecraft on another PC with the same account). It seems only the most recently obtained accessToken for a given account can reliably be used for authentication (the next-to-last token also seems to remain valid, but don't rely on it).

/validate may be called with or without a clientToken. If a clientToken is provided, it should match the one used to obtain the accessToken. The Minecraft Launcher does send a clientToken to /validate.

Endpoint

/validate

Payload

{
    "accessToken": "valid accessToken",
    "clientToken": "associated clientToken" // optional, see above
}

Response

Returns an empty payload (204 No Content) if successful, an error JSON with status 403 Forbidden otherwise.

Signout

Invalidates accessTokens using an account's username and password.

Endpoint

/signout

Payload

{
    "username": "mojang account name",
    "password": "mojang account password"
}

Response

Returns an empty payload if successful.

Invalidate

Invalidates accessTokens using a client/access token pair.

Endpoint

/invalidate

Payload

{
    "accessToken": "valid accessToken",
    "clientToken": "client identifier"   // This needs to be identical to the one used
                                         // to obtain the accessToken in the first place
}

Response

Returns an empty payload if successful.

Joining a Server

See Protocol Encryption#Authentication

Examples

Kotlin | Full Yggdrasil wrapper in Kotlin.

Java | Legacy full Yggdrasil wrapper in Java.