mcauthjs v1.1.0

McAuthJS

Minecraft / Mojang Authentication API (Yggdrasil) wrapper written in JavaScript.

Based on the information found at https://wiki.vg/Authentication.

Getting Started

It is recommended that you read https://wiki.vg/Authentication before using this in your project. It contains important details that will prevent you from writing broken code.

Live Example

todo. at some point, a link to a web based example will be here.

Install

Using npm:

npm install mcauthjs --save

Or download mcauthjs.js and put it somewhere in your project.

If you used npm to install the package, reference it in your source like this:

const mcauth = require('mcauthjs');

If you downloaded the file manually, provide a path to mcauthjs.js:

const mcauth = require('./mcauthjs.js');

Functions

mcauthjs exports five functions:

function authenticate(email, pass, clientToken, onComplete);

function refresh(accessToken, clientToken, onComplete);

function signout(email, pass, onComplete);

function validate(accessToken, clientToken, onComplete);

function invalidate(accessToken, clientToken, onComplete);

Each function corresponds directly to a Yggdrasil endpoint. Each endpoint is listed in detail at https://wiki.vg/Authentication.

All of the functions have a callback parameter, named onComplete. When the requested operation completes, onComplete is called with an object containing the results of the call. Certain properties on the result object only exist when specific conditions are met, such as an error being returned from the API. See the Errors section below for details.

authenticate(email, pass, clientToken, onComplete)

This gets an accessToken, optionally a clientToken, and information about the user account from the Mojang servers. Example usage:

const mcauth = require('mcauthjs');

mcauth.authenticate("email or username", "password", null or existing token, (result) => {
	if(result.fail) {
		console.log("Error type: " + result.error.error);
		console.log("Error: " + result.error.errorMessage);
		console.log("Cause: " + result.error.cause);
		return;
	}
	
	console.log("Username: " + result.user.username);
	console.log("clientToken: " + result.clientToken);
});

You should keep in mind that https://wiki.vg/Authentication isn't entirely accurate with the properties returned by the API. Most of the ones listed there don't exist.

When calling this function in your application, you must cache the returned clientToken and send it with future requests. If your application can't locate a cached clientToken, pass null to the authenticate function and cache the returned token. Keep in mind that failing to pass a clientToken to authenticate will cause all of the user's accessTokens to be invalidated.

refresh(accessToken, clientToken, onComplete)

This function refreshes a valid access token. This can be used to keep a user logged in between gaming sessions. accessTokens should be stored to disk along with the clientToken. Never store the user's password. Usage:

const mcauth = require('mcauthjs');

mcauth.refresh("access token", "client token", (result) => {
	if(result.fail) {
		// handle error
		return;
	}
	
	// handle success
});

I'm not sure what sort of errors the Mojang API throws here. Regardless, mcauthjs should handle it, and the error contents should be in result.error.

signout(email, pass, onComplete)

This immediately invalidates all accessTokens attached to an account. There is no data in the result unless there's an error. Usage:

const mcauth = require('mcauthjs');

mcauth.signout("email or username", "password", (result) => {
	if(result.fail) {
		// handle failure (invalid username or password is most likely here)
		return;
	}
	
	// no more data in result object.
	// handle success
});

I don't know what use this is, but it exists.

validate(accessToken, clientToken, onComplete)

This function checks if an accessToken is valid. There is no data in the result object unless the operation failed. Usage:

const mcauth = require('mcauthjs');

mcauth.validate("access token", "client token", (result) => {
	if(result.fail) {
		if(result.statusCode == 403) {
			// this indicates invalid accessToken
			return;
		}
		// some other error
		return;
	};
	
	// the accessToken is valid
});

According to https://wiki.vg/Authentication, the Minecraft launcher calls this at startup to see if its saved accessToken is any good. If the token is rotten and dead, it calls refresh(accessToken, clientToken, onComplete with the dead accessToken in attempt to refresh it. If that fails, the user must log in again using their username and password to get a new accessToken.

invalidate(accessToken, clientToken, onComplete)

This function expunges an accessToken from existence. There is no data in the result object.

const mcauth = require('mcauthjs');

mcauth.validate("access token", "client token", (result) => {
	if(result.fail) {
		// something didn't work
		return;
	};
	
	// the accessToken was obliterated
});

Errors

mcauthjs tries to handle errors as nicely as it can. You can check if the requested operation succeeded by looking at the fail property. The error property will only exist in the result object if fail is true. The properties that you expect to exist will be either null or undefined (like response.user) if fail is true.

The error object will always contain at least two properties: error.error and error.errorMessage. The error.error property is a somewhat machine readable error name that you can use to identify what went wrong in code (think error ID). The error.errorMessage property is a message that could be directly shown to the user.

Sometimes, there's an error.cause property that tells you why the error was thrown, but don't count on it existing.