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. accessToken
s 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 accessToken
s 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.