Launcher Login

Launcher login uses the Yggdrasil authserver protocol. AsterYggdrasil reuses site accounts as identities and exposes Minecraft profiles under each account for launchers.

Login Flow

Launchers call:

POST /api/yggdrasil/authserver/authenticate

The request usually includes:

• username: account email, account name, or Minecraft profile name when enabled.
• password: site account password.
• clientToken: client identifier generated by the launcher.
• agent: Minecraft agent.
• requestUser: whether user properties should be returned.

Successful responses include:

• accessToken
• clientToken
• availableProfiles
• selectedProfile
• optional user

clientToken

clientToken identifies the launcher client. It is not an authentication secret. When supplied, refresh and validate verify that it matches the token; invalidate follows the Yggdrasil spec and only checks accessToken, so clientToken does not affect revocation.

If omitted, the server generates one and returns it.

selectedProfile

A site account can have multiple Minecraft profiles. After login, the launcher receives availableProfiles and selectedProfile.

If the account has no profile, login may still succeed, but there is no selected profile that can join a server. The user needs to create a profile first.

Refresh keeps or updates selected profile data and returns a new access token. The old access token becomes invalid.

Token Lifecycle

Yggdrasil tokens have TTL and active-token limits:

• yggdrasil_token_ttl_days
• yggdrasil_max_active_tokens

The server prunes old tokens when issuing new ones, and the yggdrasil-token-cleanup runtime task removes expired or revoked tokens.

invalidate revokes one token. signout uses account credentials to revoke all Yggdrasil tokens for that user.

Join Verification

The Minecraft client calls:

POST /api/yggdrasil/sessionserver/session/minecraft/join

The Minecraft server then calls:

GET /api/yggdrasil/sessionserver/session/minecraft/hasJoined

A successful hasJoined response includes profile id, name, and properties. Returned profile properties are signed and can be verified with the public key from metadata.

Profile Name Login

yggdrasil_allow_profile_name_login controls whether users can log in with Minecraft profile names.

When disabled, feature.non_email_login reflects the policy, and launchers should not assume profile-name login is available.

Common Failures

• Access token expired or revoked: log in again.
• clientToken mismatch: refresh with the same client configuration or log in again.
• selected profile missing: create a profile or select an existing one.
• profile deleted: related tokens are revoked; create a profile and log in again.