https://wiki.vg/api.php?action=feedcontributions&user=Jonathanperret&feedformat=atomwiki.vg - User contributions [en]2024-03-28T13:16:34ZUser contributionsMediaWiki 1.34.4https://wiki.vg/index.php?title=Legacy_Mojang_Authentication&diff=6800Legacy Mojang Authentication2015-08-15T22:05:34Z<p>Jonathanperret: /* Errors */ add "Invalid credentials." message obtained when /authenticate rate-limits</p>
<hr />
<div>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].<br />
<br />
== Request format ==<br />
<br />
All requests to Yggdrasil are made to the following server:<br />
<br />
https://authserver.mojang.com<br />
<br />
Further, they are expected to fulfill the following rules:<br />
<br />
* Are <code>POST</code> requests<br />
* Have the <code>Content-Type</code> header set to <code>application/json</code><br />
* Contain a [[wikipedia:JSON|JSON]]-encoded dictionary as payload<br />
<br />
If a request was successful the server will respond with:<br />
<br />
* Status code <code>200</code><br />
* A [[wikipedia:JSON|JSON]]-encoded dictionary according to the specifications below<br />
<br />
If however a request fails, the server will respond with:<br />
<br />
* An appropriate, non-200 [[wikipedia:List of HTTP status codes|HTTP status code]]<br />
* A [[wikipedia:JSON|JSON]]-encoded dictionary following this format:<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"error": "Short description of the error",<br />
"errorMessage": "Longer description which can be shown to the user",<br />
"cause": "Cause of the error" // optional<br />
}<br />
</syntaxhighlight><br />
<br />
== Errors ==<br />
<br />
These are some of the errors that can be encountered:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Error<br />
! Cause<br />
! Error message<br />
! Notes<br />
|-<br />
| <code>Method Not Allowed</code><br />
|<br />
| The method specified in the request is not allowed for the resource identified by the request URI<br />
| Something other than a POST request was received.<br />
|-<br />
| <code>Not Found</code><br />
|<br />
| The server has not found anything matching the request URI<br />
| Non-existing endpoint was called.<br />
|-<br />
| <code>ForbiddenOperationException</code><br />
| <code>UserMigratedException</code><br />
| Invalid credentials. Account migrated, use e-mail as username.<br />
| <br />
|-<br />
| <code>ForbiddenOperationException</code><br />
| <br />
| Invalid credentials. Invalid username or password.<br />
| <br />
|-<br />
| <code>ForbiddenOperationException</code><br />
| <br />
| Invalid credentials.<br />
| Too many login attempts with this username recently (see <code>/authenticate</code>). Note that username and password may still be valid!<br />
|-<br />
| <code>ForbiddenOperationException</code><br />
| <br />
| Invalid token.<br />
| <code>accessToken</code> was invalid.<br />
|-<br />
| <code>IllegalArgumentException</code><br />
| <br />
| Access token already has a profile assigned.<br />
| Selecting profiles isn't implemented yet.<br />
|-<br />
| <code>IllegalArgumentException</code><br />
| <br />
| credentials is null<br />
| Username/password was not submitted.<br />
|-<br />
| <code>Unsupported Media Type</code><br />
| <br />
| 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<br />
| Data was not submitted as application/json<br />
|}<br />
<br />
== Authenticate ==<br />
<br />
Authenticates a user using their password.<br />
<br />
=== Endpoint ===<br />
<br />
/authenticate<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"agent": { // defaults to Minecraft<br />
"name": "Minecraft", // For Mojang's other game Scrolls, "Scrolls" should be used<br />
"version": 1 // This number might be increased<br />
// by the vanilla client in the future<br />
},<br />
"username": "mojang account name", // Can be an email address or player name for<br />
// unmigrated accounts<br />
"password": "mojang account password",<br />
"clientToken": "client identifier" // optional<br />
}<br />
</syntaxhighlight><br />
<br />
The <code>clientToken</code> should be a randomly generated identifier and must be identical for each 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.<br />
<br />
=== Response ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "random access token", // hexadecimal<br />
"clientToken": "client identifier", // identical to the one received<br />
"availableProfiles": [ // only present if the agent field was received<br />
{<br />
"id": "profile identifier", // hexadecimal<br />
"name": "player name",<br />
"legacy": true or false // In practice, this field only appears in the response if true. Default to false.<br />
}<br />
],<br />
"selectedProfile": { // only present if the agent field was received<br />
"id": "profile identifier",<br />
"name": "player name",<br />
"legacy": true or false<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
== Refresh ==<br />
<br />
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]]). <br />
<br />
=== Endpoint ===<br />
<br />
/refresh<br />
<br />
=== Payload ===<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "valid accessToken",<br />
"clientToken": "client identifier", // This needs to be identical to the one used<br />
// to obtain the accessToken in the first place<br />
"selectedProfile": { // optional; sending it will result in an error<br />
"id": "profile identifier", // hexadecimal<br />
"name": "player name"<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Note: The provided <code>accessToken</code> gets invalidated.<br />
<br />
=== Response ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "random access token", // hexadecimal<br />
"clientToken": "client identifier", // identical to the one received<br />
"selectedProfile": {<br />
"id": "profile identifier", // hexadecimal<br />
"name": "player name"<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
== Validate ==<br />
<br />
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.<br />
<br />
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).<br />
<br />
<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>.<br />
<br />
=== Endpoint ===<br />
<br />
/validate<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "valid accessToken"<br />
"clientToken": "associated clientToken" // optional, see above<br />
}<br />
</syntaxhighlight><br />
<br />
=== Response ===<br />
<br />
Returns an empty payload (<code>204 No Content</code>) if successful, an error JSON with status <code>403 Forbidden</code> otherwise.<br />
<br />
== Signout ==<br />
<br />
Invalidates <code>accessToken</code>s using an account's username and password.<br />
<br />
=== Endpoint ===<br />
<br />
/signout<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"username": "mojang account name",<br />
"password": "mojang account password"<br />
}<br />
</syntaxhighlight><br />
<br />
=== Response ===<br />
<br />
Returns an empty payload if successful.<br />
<br />
== Invalidate ==<br />
<br />
Invalidates <code>accessToken</code>s using a client/access token pair.<br />
<br />
=== Endpoint ===<br />
<br />
/invalidate<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "valid accessToken",<br />
"clientToken": "client identifier" // This needs to be identical to the one used<br />
// to obtain the accessToken in the first place<br />
}<br />
</syntaxhighlight><br />
<br />
=== Response ===<br />
<br />
Returns an empty payload if successful.<br />
<br />
== Joining a Server ==<br />
<br />
See [[Protocol Encryption#Authentication]]<br />
<br />
[[Category:Protocol Details]]<br />
[[Category:Minecraft Modern]]</div>Jonathanperrethttps://wiki.vg/index.php?title=Legacy_Mojang_Authentication&diff=6799Legacy Mojang Authentication2015-08-15T22:00:57Z<p>Jonathanperret: /* Response */ mention rate-limiting present on /authenticate</p>
<hr />
<div>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].<br />
<br />
== Request format ==<br />
<br />
All requests to Yggdrasil are made to the following server:<br />
<br />
https://authserver.mojang.com<br />
<br />
Further, they are expected to fulfill the following rules:<br />
<br />
* Are <code>POST</code> requests<br />
* Have the <code>Content-Type</code> header set to <code>application/json</code><br />
* Contain a [[wikipedia:JSON|JSON]]-encoded dictionary as payload<br />
<br />
If a request was successful the server will respond with:<br />
<br />
* Status code <code>200</code><br />
* A [[wikipedia:JSON|JSON]]-encoded dictionary according to the specifications below<br />
<br />
If however a request fails, the server will respond with:<br />
<br />
* An appropriate, non-200 [[wikipedia:List of HTTP status codes|HTTP status code]]<br />
* A [[wikipedia:JSON|JSON]]-encoded dictionary following this format:<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"error": "Short description of the error",<br />
"errorMessage": "Longer description which can be shown to the user",<br />
"cause": "Cause of the error" // optional<br />
}<br />
</syntaxhighlight><br />
<br />
== Errors ==<br />
<br />
These are some of the errors that can be encountered:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Error<br />
! Cause<br />
! Error message<br />
! Notes<br />
|-<br />
| <code>Method Not Allowed</code><br />
|<br />
| The method specified in the request is not allowed for the resource identified by the request URI<br />
| Something other than a POST request was received.<br />
|-<br />
| <code>Not Found</code><br />
|<br />
| The server has not found anything matching the request URI<br />
| Non-existing endpoint was called.<br />
|-<br />
| <code>ForbiddenOperationException</code><br />
| <code>UserMigratedException</code><br />
| Invalid credentials. Account migrated, use e-mail as username.<br />
| <br />
|-<br />
| <code>ForbiddenOperationException</code><br />
| <br />
| Invalid credentials. Invalid username or password.<br />
| <br />
|-<br />
| <code>ForbiddenOperationException</code><br />
| <br />
| Invalid token.<br />
| <code>accessToken</code> was invalid.<br />
|-<br />
| <code>IllegalArgumentException</code><br />
| <br />
| Access token already has a profile assigned.<br />
| Selecting profiles isn't implemented yet.<br />
|-<br />
| <code>IllegalArgumentException</code><br />
| <br />
| credentials is null<br />
| Username/password was not submitted.<br />
|-<br />
| <code>Unsupported Media Type</code><br />
| <br />
| 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<br />
| Data was not submitted as application/json<br />
|}<br />
<br />
== Authenticate ==<br />
<br />
Authenticates a user using their password.<br />
<br />
=== Endpoint ===<br />
<br />
/authenticate<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"agent": { // defaults to Minecraft<br />
"name": "Minecraft", // For Mojang's other game Scrolls, "Scrolls" should be used<br />
"version": 1 // This number might be increased<br />
// by the vanilla client in the future<br />
},<br />
"username": "mojang account name", // Can be an email address or player name for<br />
// unmigrated accounts<br />
"password": "mojang account password",<br />
"clientToken": "client identifier" // optional<br />
}<br />
</syntaxhighlight><br />
<br />
The <code>clientToken</code> should be a randomly generated identifier and must be identical for each 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.<br />
<br />
=== Response ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "random access token", // hexadecimal<br />
"clientToken": "client identifier", // identical to the one received<br />
"availableProfiles": [ // only present if the agent field was received<br />
{<br />
"id": "profile identifier", // hexadecimal<br />
"name": "player name",<br />
"legacy": true or false // In practice, this field only appears in the response if true. Default to false.<br />
}<br />
],<br />
"selectedProfile": { // only present if the agent field was received<br />
"id": "profile identifier",<br />
"name": "player name",<br />
"legacy": true or false<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
== Refresh ==<br />
<br />
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]]). <br />
<br />
=== Endpoint ===<br />
<br />
/refresh<br />
<br />
=== Payload ===<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "valid accessToken",<br />
"clientToken": "client identifier", // This needs to be identical to the one used<br />
// to obtain the accessToken in the first place<br />
"selectedProfile": { // optional; sending it will result in an error<br />
"id": "profile identifier", // hexadecimal<br />
"name": "player name"<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Note: The provided <code>accessToken</code> gets invalidated.<br />
<br />
=== Response ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "random access token", // hexadecimal<br />
"clientToken": "client identifier", // identical to the one received<br />
"selectedProfile": {<br />
"id": "profile identifier", // hexadecimal<br />
"name": "player name"<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
== Validate ==<br />
<br />
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.<br />
<br />
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).<br />
<br />
<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>.<br />
<br />
=== Endpoint ===<br />
<br />
/validate<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "valid accessToken"<br />
"clientToken": "associated clientToken" // optional, see above<br />
}<br />
</syntaxhighlight><br />
<br />
=== Response ===<br />
<br />
Returns an empty payload (<code>204 No Content</code>) if successful, an error JSON with status <code>403 Forbidden</code> otherwise.<br />
<br />
== Signout ==<br />
<br />
Invalidates <code>accessToken</code>s using an account's username and password.<br />
<br />
=== Endpoint ===<br />
<br />
/signout<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"username": "mojang account name",<br />
"password": "mojang account password"<br />
}<br />
</syntaxhighlight><br />
<br />
=== Response ===<br />
<br />
Returns an empty payload if successful.<br />
<br />
== Invalidate ==<br />
<br />
Invalidates <code>accessToken</code>s using a client/access token pair.<br />
<br />
=== Endpoint ===<br />
<br />
/invalidate<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "valid accessToken",<br />
"clientToken": "client identifier" // This needs to be identical to the one used<br />
// to obtain the accessToken in the first place<br />
}<br />
</syntaxhighlight><br />
<br />
=== Response ===<br />
<br />
Returns an empty payload if successful.<br />
<br />
== Joining a Server ==<br />
<br />
See [[Protocol Encryption#Authentication]]<br />
<br />
[[Category:Protocol Details]]<br />
[[Category:Minecraft Modern]]</div>Jonathanperrethttps://wiki.vg/index.php?title=Legacy_Mojang_Authentication&diff=6798Legacy Mojang Authentication2015-08-15T21:56:40Z<p>Jonathanperret: /* Validate */ rewrite description after some testing</p>
<hr />
<div>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].<br />
<br />
== Request format ==<br />
<br />
All requests to Yggdrasil are made to the following server:<br />
<br />
https://authserver.mojang.com<br />
<br />
Further, they are expected to fulfill the following rules:<br />
<br />
* Are <code>POST</code> requests<br />
* Have the <code>Content-Type</code> header set to <code>application/json</code><br />
* Contain a [[wikipedia:JSON|JSON]]-encoded dictionary as payload<br />
<br />
If a request was successful the server will respond with:<br />
<br />
* Status code <code>200</code><br />
* A [[wikipedia:JSON|JSON]]-encoded dictionary according to the specifications below<br />
<br />
If however a request fails, the server will respond with:<br />
<br />
* An appropriate, non-200 [[wikipedia:List of HTTP status codes|HTTP status code]]<br />
* A [[wikipedia:JSON|JSON]]-encoded dictionary following this format:<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"error": "Short description of the error",<br />
"errorMessage": "Longer description which can be shown to the user",<br />
"cause": "Cause of the error" // optional<br />
}<br />
</syntaxhighlight><br />
<br />
== Errors ==<br />
<br />
These are some of the errors that can be encountered:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Error<br />
! Cause<br />
! Error message<br />
! Notes<br />
|-<br />
| <code>Method Not Allowed</code><br />
|<br />
| The method specified in the request is not allowed for the resource identified by the request URI<br />
| Something other than a POST request was received.<br />
|-<br />
| <code>Not Found</code><br />
|<br />
| The server has not found anything matching the request URI<br />
| Non-existing endpoint was called.<br />
|-<br />
| <code>ForbiddenOperationException</code><br />
| <code>UserMigratedException</code><br />
| Invalid credentials. Account migrated, use e-mail as username.<br />
| <br />
|-<br />
| <code>ForbiddenOperationException</code><br />
| <br />
| Invalid credentials. Invalid username or password.<br />
| <br />
|-<br />
| <code>ForbiddenOperationException</code><br />
| <br />
| Invalid token.<br />
| <code>accessToken</code> was invalid.<br />
|-<br />
| <code>IllegalArgumentException</code><br />
| <br />
| Access token already has a profile assigned.<br />
| Selecting profiles isn't implemented yet.<br />
|-<br />
| <code>IllegalArgumentException</code><br />
| <br />
| credentials is null<br />
| Username/password was not submitted.<br />
|-<br />
| <code>Unsupported Media Type</code><br />
| <br />
| 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<br />
| Data was not submitted as application/json<br />
|}<br />
<br />
== Authenticate ==<br />
<br />
Authenticates a user using their password.<br />
<br />
=== Endpoint ===<br />
<br />
/authenticate<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"agent": { // defaults to Minecraft<br />
"name": "Minecraft", // For Mojang's other game Scrolls, "Scrolls" should be used<br />
"version": 1 // This number might be increased<br />
// by the vanilla client in the future<br />
},<br />
"username": "mojang account name", // Can be an email address or player name for<br />
// unmigrated accounts<br />
"password": "mojang account password",<br />
"clientToken": "client identifier" // optional<br />
}<br />
</syntaxhighlight><br />
<br />
The <code>clientToken</code> should be a randomly generated identifier and must be identical for each 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.<br />
<br />
=== Response ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "random access token", // hexadecimal<br />
"clientToken": "client identifier", // identical to the one received<br />
"availableProfiles": [ // only present if the agent field was received<br />
{<br />
"id": "profile identifier", // hexadecimal<br />
"name": "player name",<br />
"legacy": true or false // In practice, this field only appears in the response if true. Default to false.<br />
}<br />
],<br />
"selectedProfile": { // only present if the agent field was received<br />
"id": "profile identifier",<br />
"name": "player name",<br />
"legacy": true or false<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
== Refresh ==<br />
<br />
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]]). <br />
<br />
=== Endpoint ===<br />
<br />
/refresh<br />
<br />
=== Payload ===<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "valid accessToken",<br />
"clientToken": "client identifier", // This needs to be identical to the one used<br />
// to obtain the accessToken in the first place<br />
"selectedProfile": { // optional; sending it will result in an error<br />
"id": "profile identifier", // hexadecimal<br />
"name": "player name"<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Note: The provided <code>accessToken</code> gets invalidated.<br />
<br />
=== Response ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "random access token", // hexadecimal<br />
"clientToken": "client identifier", // identical to the one received<br />
"selectedProfile": {<br />
"id": "profile identifier", // hexadecimal<br />
"name": "player name"<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
== Validate ==<br />
<br />
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.<br />
<br />
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).<br />
<br />
<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>.<br />
<br />
=== Endpoint ===<br />
<br />
/validate<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "valid accessToken"<br />
"clientToken": "associated clientToken" // optional, see above<br />
}<br />
</syntaxhighlight><br />
<br />
=== Response ===<br />
<br />
Returns an empty payload (<code>204 No Content</code>) if successful, an error JSON with status <code>403 Forbidden</code> otherwise.<br />
<br />
== Signout ==<br />
<br />
Invalidates <code>accessToken</code>s using an account's username and password.<br />
<br />
=== Endpoint ===<br />
<br />
/signout<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"username": "mojang account name",<br />
"password": "mojang account password"<br />
}<br />
</syntaxhighlight><br />
<br />
=== Response ===<br />
<br />
Returns an empty payload if successful.<br />
<br />
== Invalidate ==<br />
<br />
Invalidates <code>accessToken</code>s using a client/access token pair.<br />
<br />
=== Endpoint ===<br />
<br />
/invalidate<br />
<br />
=== Payload ===<br />
<br />
<syntaxhighlight lang="javascript"><br />
{<br />
"accessToken": "valid accessToken",<br />
"clientToken": "client identifier" // This needs to be identical to the one used<br />
// to obtain the accessToken in the first place<br />
}<br />
</syntaxhighlight><br />
<br />
=== Response ===<br />
<br />
Returns an empty payload if successful.<br />
<br />
== Joining a Server ==<br />
<br />
See [[Protocol Encryption#Authentication]]<br />
<br />
[[Category:Protocol Details]]<br />
[[Category:Minecraft Modern]]</div>Jonathanperrethttps://wiki.vg/index.php?title=Server_List_Ping&diff=3827Server List Ping2013-05-21T12:44:27Z<p>Jonathanperret: Undo revision 3716 by Manawyrm (talk) -- sorry, it's actually big endian !</p>
<hr />
<div>Minecraft supports querying the MOTD, player count, max players and server version via the usual port. Unlike [[Query]], the server list ping interface is always enabled.<br />
<br />
== Client -> Server ==<br />
<br />
The client initiates a TCP connection to the minecraft server on the standard port. Instead of doing auth and logging in (as detailed in [[Protocol Encryption]]), it sends the two byte sequence <code>FE 01</code>. This is a [[Protocol#Server_List_Ping_.280xFE.29|0xFE server list ping]] packet. If the second byte (the 0x01) is missing, the server waits about 1000ms then replies with the Server -> Client format used in 1.3 and earlier.<br />
<br />
== Server -> Client ==<br />
<br />
The server responds with a [[Protocol#Disconnect.2FKick_.280xFF.29|0xFF kick]] packet. The packet begins with a single byte identifier <code>ff</code>, then a two-byte big endian short giving the length of the proceeding string in characters. You can actually ignore the length because the server closes the connection after the response is sent.<br />
<br />
After the first 3 bytes, the packet is a big-endian UCS-2 string. It begins with two characters: <code>§1</code>, followed by a null character. On the wire these look like <code>00 a7 00 31 00 00</code>.<br />
<br />
The remainder is null character (that is <code>00 00</code>) delimited fields:<br />
<br />
# Protocol version (e.g. <code>47</code>)<br />
# Minecraft server version (e.g. <code>1.4.2</code>)<br />
# Message of the day (e.g. <code>A Minecraft Server</code>)<br />
# Current player count<br />
# Max players<br />
<br />
The entire packet looks something like this:<br />
<br />
<---> first character<br />
0000000: ff00 2300 a700 3100 0000 3400 3700 0000 ....§.1...4.7...<br />
0000010: 3100 2e00 3400 2e00 3200 0000 4100 2000 1...4...2...A. .<br />
0000020: 4d00 6900 6e00 6500 6300 7200 6100 6600 M.i.n.e.c.r.a.f.<br />
0000030: 7400 2000 5300 6500 7200 7600 6500 7200 t. .S.e.r.v.e.r.<br />
0000040: 0000 3000 0000 3200 30 ..0...2.0<br />
<br />
=== Sample code ===<br />
<br />
* [https://gist.github.com/1209061 Python]<br />
* [http://forums.bukkit.org/threads/solved-minecraft-server-list-ping-php-script-for-1-4.108096/#post-1395553 PHP]<br />
* [https://gist.github.com/4574114 Java]</div>Jonathanperret