A Minecraft Java Edition account library for Java 25, covering sign-in, account management, bulk operations, an encrypted local store and a shared vault.
Features
- Sign-in routesMicrosoft browser login (authorization code with PKCE), Microsoft device-code login for a host with no browser or loopback port, OAuth refresh token, browser-cookie text, an exported cookie file (Netscape or JSON, byte-order-mark aware, size-capped), session token, and offline.
- One error modelEvery failure in the library is an AltsFailure: a Kind to branch on (UNAUTHORIZED, REAUTH_REQUIRED, NETWORK, RATE_LIMITED, NOT_ENTITLED, XBOX_DENIED, DECLINED, TIMED_OUT, CANCELLED, …), a message the library builds and that never carries a token or a path, the wait a rate limit stated, and the decoded Xbox Live refusal when there is one.
- Account management over a tokenaccountServices(account) reads the full profile (skins, capes, pending actions), entitlements as a product set, player attributes and platform ban status, the chat-signing certificate and the blocklist; creates a profile for an entitled account that has none; and changes the name, skin and cape, including a scheduled name claim around a known time.
- Public profile lookupprofileLookup() resolves a player by name or UUID, and a list of names ten per request, with no token and no account.
- Operate on accounts without logging into themaccountService().check(...) asks whether a stored token still works; refresh(...) renews it and persists the rotation.
- Bulk operationsbulk().checkAll(...), refreshAll(...), entitlementsAll(...) and importCredentials(...) run one operation over many accounts with bounded concurrency, spacing, a retry budget, progress and cancellation.
- Encrypted local storeEach runtime owns an AccountStore (alts.store()) and a HostSecrets (alts.secrets()), AES-256-GCM files in a host-chosen directory, written atomically with a rolling backup and locked to that runtime, so two runtimes, in one process or two, never write the same file.
- Per-account proxy routingA ProxyProvider names the route of each request, and a route tag routes a first sign-in that has no account yet.
- Shared vault on AVP 0.5Share a set of accounts between members through hosts that see only ciphertext, implementing the open Alt Vault Protocol 0.5 (a draft specification).
- Async cachesAsyncCache<K,V> (lazy, non-blocking, stale-while-revalidate, bounded) backs the optional per-server game stats a host supplies through GameStatsSource.
- A runtime executorEach runtime runs its blocking work on one virtual thread per task, or on the executor the host passes to the builder, and close() shuts down only the one it created.
- A closeable runtimeAltsRuntime is AutoCloseable: close() flushes and unlocks the stores, closes the transport, and ends whatever was still waiting on the runtime.
- Host-agnosticThe library never imports a host type.
- A frozen, narrow APIThe jar is the named module lol.trq.alts; the implementation lives under lol.trq.alts.internal, which is not exported or documented.
- Obfuscation-safeDTOs are records with @SerializedName on every component; the stored AltAccount, a class, carries it on every field.
Quick start
// 1. Wire the host seams once at startup. H is your texture-handle type; a host that draws no
// avatars can use any type and leave textureUploader unset.
// build() also reads whatever store is already on disk, so alts.store().accounts()
// is populated the moment it returns. Close the runtime when the host is done with it.
AltsRuntime<MyHandle> alts = new AltsRuntime.Builder<MyHandle>()
.sessionInjector(new MySessionInjector()) // REQUIRED: install a SessionData as the live session
.vaultDirectory(() -> myDataDir) // REQUIRED: where the two encrypted store files live
.mainThread(myExecutor::execute) // REQUIRED: run a task on the host's main thread
.toastSink(new MyToastSink()) // REQUIRED: surface a notification
.textureUploader(new MyUploader()) // optional: avatar bytes -> host texture
.microsoftAuth(MicrosoftAuthConfig.of(MY_AZURE_CLIENT_ID)) // optional: your own Azure app id
.build();
// 2. Sign in through the browser.
alts.loginService().loginMicrosoft(LoginMode.ADD)
.thenAccept(result -> { /* result.success(), result.account(), result.failure() */ });
// Or with a device code, when there is no browser to open.
alts.loginService().loginDeviceCode(
(userCode, verificationUri, expiresAt) -> show(verificationUri, userCode),
LoginMode.ADD)
.thenAccept(result -> { /* result.success(), result.failure().map(AltsFailure::kind) */ });
// 3. Operate on a stored account without logging into it. A failure throws AltsException;
// switch on e.kind().
AccountServices services = alts.accountServices(account);
PlayerProfile profile = services.profile().fetch();
Entitlements owned = services.entitlements().fetch();
// 4. On shutdown: write what is pending and release the store files.
alts.close();The getting started guide walks through every step, and the examples compile against the library.