yggdrasil

README

go-yggdrasil

Single file library for Mojang's Yggdrasil API written in Golang without extra dependencies

Installing

go get github.com/JoshuaDoes/go-yggdrasil

Recommended authentication procedure

Note: This procedure is based on the official Minecraft launcher's authentication logic.

When authenticating with Yggdrasil, you should use *yggdrasil.Client.Authenticate() only if you do not already have an access/client token pair stored somewhere, as Yggdrasil's /authenticate endpoint is severely rate-limited. If you have an access/client token pair, you should use *yggdrasil.Client.Validate() on a pre-initialized *yggdrasil.Client variable to make sure it is still valid. If it is not, you should then use *yggdrasil.Client.Refresh() to get a new access token and have it automatically be stored in the *yggdrasil.Client variable. Should this fail, however, then it is safe to use *yggdrasil.Client.Authenticate() again and store the returned access/client token pair for future use.

Additional notes

When an authentication is successful, your *yggdrasil.Client variable will contain the client's access/client token pair, the current selected profile (changing this is not yet implemented in Yggdrasil), and the current user.

When using any available go-yggdrasil functions, any internal errors will be returned as *yggdrasil.Error.FuncError rather than be classically available as an error type. Any errors returned from Yggdrasil itself will be returned as *yggdrasil.Error.

Authentication example

package main

import "fmt"
import "github.com/JoshuaDoes/yggdrasil"

var yggdrasilClient *yggdrasil.Client

func main() {
	yggdrasilClient = &yggdrasil.Client{ClientToken: "your client token here"}

	//Auth with Minecraft version 1
	authResponse, err := yggdrasilClient.Authenticate("your email/username here", "your password here", "Minecraft", 1)
	if err != nil {
		fmt.Println("Error: " + fmt.Sprintf("%v", err))
	} else {
		//Print access/client token pair
		fmt.Println("Access Token: " + authResponse.AccessToken)
		fmt.Println("Client Token: " + authResponse.ClientToken)
	}
}

Output

> go run main.go
Access Token: 32 char hexadecimal access token
Client Token: specified client token

License

The source code for go-yggdrasil is released under the MIT License. See LICENSE for more details.

Donations

All donations are appreciated and helps me stay awake at night to work on this more. Even if it's not much, it helps a lot in the long run! You can find the donation link here: Donation Link

Documentation

Overview

Package yggdrasil provides methods to utilize Mojang's Yggdrasil API.

Index

• type Agent
• type AuthenticationRequest
• type AuthenticationResponse
• type Client
  • func (client *Client) Authenticate(username, password, gameName string, gameVersion int) (*AuthenticationResponse, *Error)
  • func (client *Client) Invalidate() *Error
  • func (client *Client) Refresh() (*RefreshResponse, *Error)
  • func (client *Client) Signout(username, password string) (bool, *Error)
  • func (client *Client) Validate() (bool, *Error)
• type Error
• type InvalidateRequest
• type Profile
• type Property
• type RefreshRequest
• type RefreshResponse
• type SignoutRequest
• type User
• type ValidateRequest

Types

type Agent

type Agent struct {
	Name    string `json:"name"`
	Version int    `json:"version"`
}

Agent holds data about the game that was authenticated for.

type AuthenticationRequest

type AuthenticationRequest struct {
	Agent       Agent  `json:"agent"`
	Username    string `json:"username"`
	Password    string `json:"password"`
	ClientToken string `json:"clientToken"`
	RequestUser bool   `json:"requestUser"`
}

AuthenticationRequest holds data used to make an authentication request.

type AuthenticationResponse

type AuthenticationResponse struct {
	AccessToken       string    `json:"accessToken"`
	ClientToken       string    `json:"clientToken"`
	AvailableProfiles []Profile `json:"availableProfiles"`
	SelectedProfile   Profile   `json:"selectedProfile"`
	User              User      `json:"user"`
}

AuthenticationResponse holds data returned from a successful authentication request.

type Client

type Client struct {
	AccessToken     string
	ClientToken     string
	SelectedProfile Profile
	User            User
}

Client holds an access token and a client token. After a successful authentication, it will also hold the currently selected profile and the current user.

func (*Client) Authenticate

func (client *Client) Authenticate(username, password, gameName string, gameVersion int) (*AuthenticationResponse, *Error)

Authenticate attempts to authenticate with Yggdrasil.

func (*Client) Invalidate

func (client *Client) Invalidate() *Error

Invalidate attempts to invalidate an existing access/client token pair.

func (*Client) Refresh

func (client *Client) Refresh() (*RefreshResponse, *Error)

Refresh attempts to refresh an existing access/client token pair to get a new valid access token.

func (*Client) Signout

func (client *Client) Signout(username, password string) (bool, *Error)

Signout attempts to signout of a legacy Minecraft account.

func (*Client) Validate

func (client *Client) Validate() (bool, *Error)

Validate attempts to check whether or not an existing access/client token pair is valid.

type Error

type Error struct {
	Error        string `json:"error"`
	ErrorMessage string `json:"errorMessage"`
	Cause        string `json:"cause"`
	StatusCode   int

	FuncError error
}

Error holds data about a Yggdrasil or internal error.

type InvalidateRequest

type InvalidateRequest struct {
	AccessToken string `json:"accessToken"`
	ClientToken string `json:"clientToken"`
}

InvalidateRequest holds data used to make an invalidate request.

type Profile

type Profile struct {
	ID     string `json:"id"`
	Name   string `json:"name"`
	Legacy bool   `json:"legacy"`
}

Profile holds data about an authenticated user's profile.

type Property

type Property struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

Property holds data about an authenticated user's property.

type RefreshRequest

type RefreshRequest struct {
	AccessToken     string  `json:"accessToken"`
	ClientToken     string  `json:"clientToken"`
	SelectedProfile Profile `json:"selectedProfile"`
	RequestUser     bool    `json:"requestUser"`
}

RefreshRequest holds data used to make a refresh request.

type RefreshResponse

type RefreshResponse struct {
	AccessToken     string  `json:"accessToken"`
	ClientToken     string  `json:"clientToken"`
	SelectedProfile Profile `json:"selectedProfile"`
	User            User    `json:"user"`
}

RefreshResponse holds data returned from a successful refresh request.

type SignoutRequest

type SignoutRequest struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

SignoutRequest holds data used to make a signout request.

type User

type User struct {
	ID         string     `json:"id"`
	Properties []Property `json:"properties"`
}

User holds data about an authenticated user.

type ValidateRequest

type ValidateRequest struct {
	AccessToken string `json:"accessToken"`
	ClientToken string `json:"clientToken"`
}

ValidateRequest holds data used to make a validate request.