Authentication

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.

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  requests
 * Have the  header set to
 * Contain a JSON-encoded dictionary as payload

If a request was successful the server will respond with:


 * Status code
 * A JSON-encoded dictionary according to the specifications below

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


 * An appropriate, non-200 HTTP status code
 * A JSON-encoded dictionary following this format:

Errors
These are some of the errors that can be encountered:

Authenticate
Authenticates a user using their password.

Endpoint
/authenticate

Payload
The  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 which should then be stored by the client. This will however also invalidate all previously acquired s for this user across all clients.

Response
Note: If a user wishes to stay logged in on their computer you are strongly advised to store the received  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  field, and the   array will be empty.

Some instances in the wild have been observed of Mojang returning a flat  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  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   response. This error clears up a few seconds later.

Refresh
Refreshes a valid. 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
Note: The provided  gets invalidated.

Validate
Checks if an  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  if this returns an error.

Note that an  may be unusable for authentication with a Minecraft server, but still be good enough for. 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  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).

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

Endpoint
/validate

Response
Returns an empty payload if successful, an error JSON with status   otherwise.

Signout
Invalidates s using an account's username and password.

Endpoint
/signout

Response
Returns an empty payload if successful.

Invalidate
Invalidates s using a client/access token pair.

Endpoint
/invalidate

Response
Returns an empty payload if successful.

Joining a Server
See Protocol Encryption