Skip to main content

​
Account Management

LiquidBounce features a comprehensive account management system that allows you to manage multiple Minecraft accounts and switch between them seamlessly. The AccountManager handles all account operations including authentication, storage, and session management.

​
Account Types

LiquidBounce supports multiple account types through the AccountService system:

Microsoft Account

Premium accounts authenticated through Microsoft OAuth2 flow. Can join online servers.

Session Account

Accounts using session tokens. Can join online servers.

TheAltening

Accounts from TheAltening service. Can join online servers.

Cracked Account

Offline mode accounts. Can only join cracked servers.

​
Adding Accounts

​
Microsoft Account

Microsoft accounts use the OAuth2 authentication flow: 
AccountManager.newMicrosoftAccount { url ->
    // Open the authentication URL in a browser
    // User completes authentication
    // Account is automatically added on success
}
The OAuth flow:
  1. Calls MicrosoftAccount.buildFromOpenBrowser() with an OAuthHandler
  2. Opens a browser window for user authentication
  3. Receives authentication callback
  4. Stores the account in the accounts list
  5. Saves to configuration via ConfigSystem.store()
The AccountManager prevents multiple simultaneous login attempts by caching the active OAuth URL.

​
Session Account

Add an account using a session token: 
AccountManager.newSessionAccount(token)
Supports both:
  • Microsoft refresh tokens (starting with “M.”)
  • Session tokens from other sources

​
Cracked Account

Create an offline mode account: 
AccountManager.newCrackedAccount(
    username = "PlayerName",
    online = false  // Set to true for online UUID lookup
)
Cracked accounts can only join servers with online-mode=false. Username must be 1-16 characters.

​
TheAltening

Add accounts from TheAltening service: 
// Add existing account
AccountManager.newAlteningAccount(accountToken)

// Generate new account (requires API token)
AccountManager.generateAlteningAccount(apiToken)

​
Managing Accounts

​
Login to Account

Switch to a different account by ID: 
AccountManager.loginAccount(id)
The login process (from AccountManager.kt:82):
  1. Validates the account exists
  2. Calls account.login() to get session credentials
  3. Creates a SessionWithService instance
  4. Generates profile keys for signing
  5. Updates mc.user with new session
  6. Updates Minecraft services (session service, profile repository)
  7. Fires SessionEvent and AccountManagerLoginResultEvent

​
Direct Login

Login directly without storing the account: 
AccountManager.loginDirectAccount(account)

​
Restore Initial Session

Return to the original session from client startup: 
AccountManager.restoreInitial()
The initial session is captured during AccountManager initialization and preserved for restoration.

​
Account Organization

// Mark as favorite
AccountManager.favoriteAccount(id)
AccountManager.unfavoriteAccount(id)

// Reorder accounts
AccountManager.swapAccounts(index1, index2)
AccountManager.orderAccounts(listOf(0, 2, 1, 3))

// Remove account
val removed = AccountManager.removeAccount(id)

​
Account Storage

Accounts are stored in the configuration system: 
val accounts by list(name, mutableListOf<MinecraftAccount>(), ValueType.ACCOUNT)
The AccountManager is registered as a root config: 
ConfigSystem.root(this)
All account modifications trigger automatic persistence via ConfigSystem.store(this@AccountManager).

​
Events

The account system fires several events: 
// Fired when login completes
EventManager.callEvent(
    AccountManagerLoginResultEvent(
        username = account.profile?.username,
        error = null
    )
)

​
Session Management

LiquidBounce preserves session state through SessionBundle: 
data class SessionBundle(
    val session: Session,
    val sessionService: SessionService?,
    val profileKeys: ProfileKeyPairManager
)
This ensures proper restoration of:
  • User profile and credentials
  • Authentication services
  • Profile key pairs for message signing

​
Code References

AccountManager.kt

Main account management logic
src/main/kotlin/net/ccbluex/liquidbounce/features/account/AccountManager.kt

AccountService.kt

Account service type definitions
src/main/kotlin/net/ccbluex/liquidbounce/features/account/AccountService.kt

OAuthClient.kt

OAuth authentication flow
src/main/kotlin/net/ccbluex/liquidbounce/api/services/auth/OAuthClient.kt

SessionBundle.kt

Session state preservation
src/main/kotlin/net/ccbluex/liquidbounce/features/account/SessionBundle.kt

​
Best Practices

1

Handle Errors

Always check for error messages in result events to provide user feedback
2

Validate Tokens

Ensure tokens are not empty before passing to account creation methods
3

Avoid Duplicates

The system automatically prevents duplicate accounts by username
4

Thread Safety

Login operations use AtomicBoolean to prevent concurrent login attempts

Build docs developers (and LLMs) love

Get started for freeTalk to us