xbl3auth

Security-conscious helper library and CLI for obtaining XBL3.0 tokens for Xbox Live.

• Uses official Microsoft auth (MSAL) instead of scraping login pages.
• Never handles raw passwords: relies on browser/OS for sign-in.
• Stores refresh tokens in the OS keyring (Credential Manager, Keychain, etc.).
• Keeps XBL3.0 tokens in memory by default, printing to stdout when requested.
• Ships with a built-in public client ID and a remote config endpoint for rotation.

This library is for legitimate use with accounts you control. Respect Microsoft ToS and local laws.

Installation

poetry add xbl3auth
# or
pip install xbl3auth

CLI usage

The CLI uses, in order of precedence:

1. --client-id flag
2. XBL3AUTH_CLIENT_ID environment variable
3. Remote config endpoint
4. Built-in default client ID

Basic usage:

python -m xbl3auth

This will:

1. Resolve the effective client ID.
2. Start a device code flow (you sign in in a browser).
3. Store a refresh token in your OS keyring.
4. Fetch an XBL3.0 token and print it to stdout:

XBL3.0 x=<uhs>;<token>

Overriding the client ID

If advanced users want to supply their own Azure app registration:

1. Command-line flag

python -m xbl3auth --client-id "<your-azure-client-id>"

2. Environment variable

export XBL3AUTH_CLIENT_ID="<your-azure-client-id>"
python -m xbl3auth

JSON output

python -m xbl3auth --print-json

Library usage

from xbl3auth import XblAuthConfig, Xbl3AuthService

config = XblAuthConfig()  # uses remote/built-in client_id by default
service = Xbl3AuthService(config, account_id="default")

xbl3_token = service.get_xbl3_token()
print(xbl3_token)

To use a custom client ID:

config = XblAuthConfig(client_id="<your-client-id>")

Security model

• No credential files: No email:password lists, no plaintext token dumps by default.
• Keyring-backed: Refresh tokens are stored in the OS keyring:
  • Windows Credential Manager
  • macOS Keychain
  • GNOME Keyring / KWallet (depending on environment)
• Short-lived tokens: XBL3.0 tokens are treated as in-memory, ephemeral values.
• Logging discipline: Library is designed so callers can log error metadata without leaking secrets.

Testing

poetry install
poetry run pytest

Tests:

• Use an in-memory secret storage backend.
• Monkeypatch HTTP requests to avoid real network calls.
• Avoid touching the real keyring.