Authentication

mcproto.auth.account.Account

Base class for an authenticated Minecraft account.

mcproto.auth.account.Account.check async

check(client: AsyncClient) -> None

Check with minecraft API whether the account information stored is valid.

:raises MismatchedAccountInfoError: If the information received from the minecraft API didn't match the information currently stored in the account instance. :raises InvalidAccountAccessTokenError: If the access token is not valid.

mcproto.auth.account.InvalidAccountAccessTokenError

Bases: Exception

Exception raised when the access token of the account was reported as invalid.

mcproto.auth.account.MismatchedAccountInfoError

Bases: Exception

Exception raised when info stored in the account instance doesn't match one from API.

mcproto.auth.yggdrasil.AuthServerApiError

Bases: Exception

Exception raised on a failure from the authserver API.

mcproto.auth.yggdrasil.AuthServerApiError.msg property

msg: str

Produce a message for this error.

mcproto.auth.yggdrasil.AuthServerApiErrorType

Bases: str, Enum

Enum for various different kinds of exceptions that the authserver API can report.

mcproto.auth.yggdrasil.AuthServerApiErrorType.from_status_error classmethod

from_status_error(code: int, short_msg: str, full_msg: str, cause_msg: str | None) -> AuthServerApiErrorType

Determine the error kind based on the error data.

mcproto.auth.yggdrasil.YggdrasilAccount

Bases: Account

Minecraft account logged into using Yggdrasil (legacy/unmigrated) auth system.

mcproto.auth.yggdrasil.YggdrasilAccount.authenticate async classmethod

authenticate(client: AsyncClient, login: str, password: str) -> Self

Authenticate using the Yggdrasil system (for non-Microsoft accounts).

:param login: E-Mail of your Minecraft account, or username for (really old) Mojang accounts. :param password: Plaintext account password.

mcproto.auth.yggdrasil.YggdrasilAccount.refresh async

refresh(client: AsyncClient) -> None

Refresh the Yggdrasil access token.

This method can be called when the access token expires, to obtain a new one without having to go through a complete re-login. This can happen after some time period, or for example when someone else logs in to this minecraft account elsewhere.

mcproto.auth.yggdrasil.YggdrasilAccount.signout async

signout(client: AsyncClient, username: str, password: str) -> None

Sign out using the Yggdrasil system (for non-Microsoft accounts).

:param login: E-Mail of your Minecraft account, or username for (really old) Mojang accounts. :param password: Plaintext account password.

mcproto.auth.yggdrasil.YggdrasilAccount.validate async

validate(client: AsyncClient) -> bool

Check if the access token is (still) usable for authentication with a Minecraft server.

If this method fails, the stored access token is no longer usable for for authentcation with a Minecraft server, but should still be good enough for :meth:refresh.

This mainly happens when one has used another client (e.g. another launcher).

mcproto.auth.msa.MSAAccount

Bases: Account

Minecraft account logged into using Microsoft OAUth2 auth system.

mcproto.auth.msa.MSAAccount.from_xbox_access_token async classmethod

from_xbox_access_token(client: AsyncClient, access_token: str) -> Self

Construct the account from the xbox access token, using it to get the rest of the profile information.

See :meth:_get_access_token_from_xbox for how to obtain the access_token. Note that in most cases, you'll want to use :meth:xbox_auth rather than this method directly.

mcproto.auth.msa.MSAAccount.xbox_auth async classmethod

xbox_auth(client: AsyncClient, user_hash: str, xsts_token: str) -> Self

Authenticate using an XSTS token from Xbox Live auth (for Microsoft accounts).

See :func:mcproto.auth.microsoft.xbox.xbox_auth for how to obtain the user_hash and xsts_token.

mcproto.auth.msa.ServicesAPIError

Bases: Exception

Exception raised on a failure from the Minecraft services API.

mcproto.auth.msa.ServicesAPIError.msg property

msg: str

Produce a message for this error.

mcproto.auth.msa.ServicesAPIErrorType

Bases: str, Enum

Enum for various different kinds of exceptions that the Minecraft services API can report.

mcproto.auth.msa.ServicesAPIErrorType.from_status_error classmethod

from_status_error(code: int, err_msg: str | None) -> ServicesAPIErrorType

Determine the error kind based on the error data.

mcproto.auth.microsoft.oauth.MicrosoftOauthRequestData

Bases: TypedDict

Data obtained from Microsoft OAuth2 API after making a new authentication request.

This data specifies where (URL) we can check with the Microsoft OAuth2 servers for a client confirmation of this authentication request, how often we should check with this server, and when this request expires.

mcproto.auth.microsoft.oauth.MicrosoftOauthResponseData

Bases: TypedDict

Data obtained from Microsoft OAuth2 API after a successful authentication.

This data contains the access and refresh tokens, giving us the requested account access and the expiry information.

mcproto.auth.microsoft.oauth.MicrosoftOauthResponseError

Bases: Exception

Exception raised on a failure from the Microsoft OAuth2 API.

mcproto.auth.microsoft.oauth.MicrosoftOauthResponseError.msg property

msg: str

Produce a message for this error.

mcproto.auth.microsoft.oauth.MicrosoftOauthResponseErrorType

Bases: str, Enum

Enum for various different kinds of exceptions that the Microsoft OAuth2 API can report.

mcproto.auth.microsoft.oauth.MicrosoftOauthResponseErrorType.from_status_error classmethod

from_status_error(error: str) -> MicrosoftOauthResponseErrorType

Determine the error kind based on the error data.

mcproto.auth.microsoft.oauth.full_microsoft_oauth async

full_microsoft_oauth(client: AsyncClient, client_id: str) -> MicrosoftOauthResponseData

Perform full Microsoft Oauth2 sequence, waiting for user to authenticated (from the browser).

See :func:microsoft_oauth_request (OAuth2 start) and :func:microsoft_oauth_authenticate (OAuth2 end).

mcproto.auth.microsoft.oauth.microsoft_oauth_authenticate async

microsoft_oauth_authenticate(client: AsyncClient, client_id: str, device_code: str) -> MicrosoftOauthResponseData

Complete Microsoft Oauth2 flow and authenticate.

This functon should be called after :func:microsoft_oauth_request. If the user has authorized the request, we will get an access token back, allowing us to perform certain actions on behaf of the microsoft user that has authorized this request. Alternatively, this function will fal with :exc:MicrosoftOauthResponseError.

mcproto.auth.microsoft.oauth.microsoft_oauth_request async

microsoft_oauth_request(client: AsyncClient, client_id: str) -> MicrosoftOauthRequestData

Initiate Microsoft Oauth2 flow.

This requires a client_id, which can be obtained by creating an application on Microsoft Azure <https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app>_, with 'Allow public client flows' set to 'Yes' (can be set from the 'Authentication' tab).

This will create a device id, used to identify our request and a user code, which the user can manually enter to https://www.microsoft.com/link and confirm, after that, :func:microsoft_oauth_authenticate should be called, with the returend device id as an argument.

mcproto.auth.microsoft.xbox.XSTSErrorType

Bases: str, Enum

Enum for various different kinds of exceptions that the Xbox Secure Token Server (XSTS) API can report.

mcproto.auth.microsoft.xbox.XSTSErrorType.from_status_error classmethod

from_status_error(xerr_no: int) -> XSTSErrorType

Determine the error kind based on the error data.

mcproto.auth.microsoft.xbox.XSTSRequestError

Bases: Exception

Exception raised on a failure from the Xbox Secure Token Server (XSTS) API.

mcproto.auth.microsoft.xbox.XSTSRequestError.msg property

msg: str

Produce a message for this error.

mcproto.auth.microsoft.xbox.XboxData

Bases: NamedTuple

Xbox authentication data.

mcproto.auth.microsoft.xbox.xbox_auth async

xbox_auth(client: AsyncClient, microsoft_access_token: str, bedrock: bool = False) -> XboxData

Authenticate into Xbox Live account and obtain user hash and XSTS token.

See :func:~mcproto.auth.microsoft.oauth.full_microsoft_oauth for info on microsoft_access_token.