Sign-in and accounts¶
Xol signs you in with Microsoft's standard flow for desktop applications: OAuth 2.0 authorization code with PKCE, in your system browser. You type your password into Microsoft's website, in your own browser. Xol never sees it.
Current status¶
Waiting for Mojang's approval
Every third-party launcher's application ID has to be approved by Mojang before Minecraft Services will accept it. Xol's has been submitted and is awaiting review. Until it is approved, sign-in runs through Microsoft and Xbox Live and then stops at the Minecraft Services step with:
Minecraft services do not accept this launcher's application ID yet: Mojang has to approve it first. Nothing is wrong with your account, and nothing was saved.
This is expected for now. There is nothing you can do on your side. The sign-in chain has been implemented and reviewed but has never been run against a real account, for the same reason.
Step by step¶
-
You press "Sign in with Microsoft". Xol starts a temporary listener on
http://localhost(your own computer, a random free port) and openslogin.microsoftonline.comin your default browser. Xol does not embed a browser window, so your password manager, passkeys and two-factor prompts work as they do everywhere else, and you can check the address bar. - You sign in on Microsoft's page and approve the request. Microsoft shows you the application name and what it is asking for.
- Microsoft redirects your browser to the local listener with a one-time authorization code. Because of PKCE, that code is useless to anything other than the Xol process that started the sign-in. The listener closes immediately afterwards.
- Xol exchanges the code for tokens directly with Microsoft. Xol is a public client: there is no client secret in the app and no Xol server takes part in the exchange.
-
Xbox Live and XSTS. The Microsoft token is exchanged at
user.auth.xboxlive.comand thenxsts.auth.xboxlive.comfor a token scoped to Minecraft Services (rp://api.minecraftservices.com/). -
Minecraft Services. Xol calls
api.minecraftservices.comto obtain a Minecraft access token, checks that the account has the Minecraft: Java Edition entitlement, and reads the profile (username and UUID). If the account does not own the game, Xol stops here and says so. - Launch. The Minecraft access token is passed to the game process on your computer, exactly as the official launcher does, so you can join online-mode servers.
Microsoft's device-code flow, where you enter a short code on Microsoft's page in any browser, is built into Xol's core. With Xol's own application ID it is not offered: until Mojang approves that ID it would stop at the same step, and the launcher refuses it. Sign in with Microsoft is the way in. The one other way is the temporary test sign-in below.
Temporary test sign-in¶
Development builds can offer Test sign-in (temporary), for testing until Xol's application ID is approved. It will be removed then. Beta and stable builds never offer it.
It is off unless you ask for it. Turn it on in Settings ▸ Service ▸ Test sign-in (temporary), with the switch "Enable test sign-in (temporary)". The switch is shown in development builds only, and a beta or stable build refuses to store it at all.
It then sits beside Sign in with Microsoft in the dock and in the account menu. Switch it off and it goes away; no restart is needed.
A file named enable-test-signin in the Xol data folder still works on its own, for testers who created one before the switch existed (an ordinary file; a folder or a link with that name does not count). Either the switch or the file is enough; removing one while the other is there changes nothing.
It shows a short code and a Microsoft address. You open the address in any browser, enter the code, and the window closes by itself when you are done. From there the chain is the same as above. Accounts added this way show the word "test" in the account menu. Like the browser sign-in, it has not been run against a real account.
The browser step times out after five minutes ("Sign-in timed out. Try again."). Only one sign-in can be in progress at a time.
What Xol asks Microsoft for¶
| Scope | Why |
|---|---|
XboxLive.signin |
Required to obtain the Xbox Live token that Minecraft Services accepts. It is the only way any launcher can prove ownership of Minecraft: Java Edition. |
offline_access |
Lets Xol refresh your session without asking you to sign in again each time you play. |
Nothing else. Xol does not request access to your email, contacts, files, profile photo or any other Microsoft data.
These are the scopes of Sign in with Microsoft. The temporary test sign-in asks a different Microsoft sign-in service for Xbox Live sign-in only.
What Xol receives and where it is kept¶
| Item | Used for | Stored |
|---|---|---|
| Microsoft refresh token | Renewing your session | On your device; see below |
| Xbox Live and XSTS tokens | One step in the chain | Not stored; discarded after use |
| Minecraft access token | Launching the game, joining servers | On your device, protected the same way; expires within a day |
| Username and UUID | Showing which account is active | On your device |
Tokens are kept in accounts.json in the data folder. How they are protected depends on the system:
| System | Protection |
|---|---|
| Windows | Encrypted by the operating system (DPAPI) |
| macOS | Current builds are not signed with an Apple Developer ID. For such apps the Keychain asks for your login password, and again after every update. So these builds keep the file readable and writable only by your own user account (file mode 0600, data folder 0700). That is file-permission protection, not encryption. A build signed with a Developer ID would use the Keychain; there is none yet. |
Where Xol uses the operating system's store and none is available, it refuses to save the sign-in rather than write tokens to disk in plain text.
Moving from 0.2.3 or older on macOS¶
Sign-ins and an access key that an older Xol sealed in the Keychain are removed once, without being read, because reading them would bring up the Keychain prompt. The launcher then shows "Please sign in again":
Xol no longer uses the macOS Keychain, so it no longer asks for your Mac password. Because of that change, your sign-in had to be removed once: sign in again. Sign-ins are now kept in a file only your user account can open.
If only an access key was removed, the sentence says "paste the key again if you use one" instead. Launcher 0.3.1 has no access key field, so there is nothing to paste; updates work without a key.
None of these values is ever sent to Xol's servers, written to logs, or included in support files or crash reports. The launcher keeps tokens in its main process only; they are never passed to the interface. The game's output is scrubbed of the access token before it reaches the log Xol keeps, and launch arguments are redacted.
Refreshing¶
When the saved Minecraft session is within ten minutes of expiring, Xol renews it before launching, using the refresh token, without opening the browser. The renewed session must belong to the same player as the saved account; otherwise it is refused with "The refreshed session belongs to a different player; sign in again."
Several accounts¶
You can sign in more than one account and switch between them in the account menu. One is active at a time. Switching is disabled while a game is being prepared or is running.
Removing access¶
- In Xol: open the account menu, press the bin icon next to the account, and choose Remove. "The saved sign-in is deleted from this computer."
- At Microsoft: visit account.microsoft.com/privacy/app-access and remove Xol. Any tokens Xol holds stop working.
Every sign-in message¶
| Message | Meaning | What to do |
|---|---|---|
| Minecraft services do not accept this launcher's application ID yet: Mojang has to approve it first. Nothing is wrong with your account, and nothing was saved. (title: "Application ID not approved" or "Sign-in did not complete") | Mojang has not approved Xol's application ID yet | Nothing on your side. See Current status. |
| Microsoft sign-in is not configured: no application (client) ID. (title: "Sign-in is not available in this build") | The build was packaged without an application ID | Ask for a current build |
| This Microsoft account does not own Minecraft: Java Edition. | The entitlement check failed | Sign in with the account that bought the game. Xol cannot launch without the entitlement. The help button opens the Minecraft store page. |
| This account owns Minecraft but has not chosen a player name yet. Set one at minecraft.net, then sign in again. | The game is owned but no profile exists | Follow the help button to minecraft.net, choose a name, sign in again |
| This Microsoft account has no Xbox profile yet. Create one, then sign in again. | Xbox Live error 2148916233 | Create the profile once at xbox.com with the same Microsoft account, then try again |
| Xbox Live is not available in this account's country/region. | Xbox Live error 2148916235 | This comes from Xbox Live; Xol cannot work around it |
| This account needs adult verification on the Xbox website. | Xbox Live errors 2148916236 and 2148916237 | Complete the verification at xbox.com |
| This is a child account. An adult must add it to a Microsoft family before it can play. | Xbox Live error 2148916238 | An adult adds the account to a family group at account.microsoft.com/family. Microsoft's family settings decide whether a child account may sign in to third-party apps. |
| Xbox authorization failed (HTTP …). | Another XSTS error | Try again later |
| Xbox Live sign-in failed (HTTP …). | The Xbox Live step failed | Try again later |
| Minecraft sign-in failed (HTTP …). | Minecraft Services answered with an unexpected error | Try again later |
| Microsoft sign-in failed: … / Microsoft sign-in failed (HTTP …) | Microsoft refused the code or token request. The text after the colon is Microsoft's own. | Try again |
| Could not start sign-in: … | The test sign-in could not get a code from Microsoft | Try again |
| The sign-in code expired before it was used. Get a new code and try again. | Test sign-in: the code was not entered in time | Press Get a new code |
| The sign-in was declined on Microsoft's page. Nothing was saved. | Test sign-in: you declined the request | Start again if that was a mistake |
| Microsoft did not recognise the sign-in code. Get a new code and try again. | Test sign-in | Press Get a new code |
| The test sign-in is not switched on in this copy of Xol. | The switch in Settings ▸ Service is off and there is no enable-test-signin file, or this is not a development build |
|
| Sign-in response failed validation. | The response that reached the local listener did not match the request Xol made | Start the sign-in again from Xol |
| Sign-in timed out. Try again. | The browser step was not finished within five minutes | Start again |
| Sign-in cancelled. | You pressed Cancel | |
| A sign-in is already in progress. Finish it in your browser, or cancel it first. | Finish or cancel the first one | |
| Secure credential storage is unavailable on this system, so Xol will not save a sign-in. On Linux, install and unlock a keyring (GNOME Keyring or KWallet). | No OS secure store | Xol refuses to store tokens in plain text. On Windows the store is part of the system, and current macOS builds use a private file instead. |
Where an error has a help page, the panel has an Open help page button. It opens only addresses on the launcher's fixed list: Microsoft's sign-in and account pages, aka.ms, minecraft.net, xbox.com, optifine.net, and xol.dev, launcher.xol.dev and docs.xol.dev.
Microsoft's side¶
When you sign in, your computer talks directly to Microsoft, Xbox Live and Minecraft Services. Their handling of your data is covered by the Microsoft Privacy Statement. The public walkthrough of this flow is at launcher.xol.dev/sign-in.