Yggdrasil API

AsterYggdrasil's protocol API root is:

/api/yggdrasil

This root serves Minecraft launchers, authlib-injector, and Minecraft servers. It does not return the project admin API envelope, and protocol errors follow the Yggdrasil/authlib-injector shape.

API Location Indication

The site homepage / returns:

X-Authlib-Injector-API-Location: /api/yggdrasil/

This is authlib-injector API Location Indication. Launchers that support ALI can accept the site URL and discover the real Yggdrasil API root from the response header.

For direct authlib-injector configuration, use the full API root:

-javaagent:authlib-injector.jar=https://example.com/api/yggdrasil

Metadata

GET /api/yggdrasil
GET /api/yggdrasil/

Metadata includes:

• meta.serverName: display name.
• meta.implementationName: implementation name, currently AsterYggdrasil.
• meta.implementationVersion: running service version.
• meta.feature.non_email_login: whether non-email login is allowed, controlled by yggdrasil_allow_profile_name_login.
• skinDomains: texture URL domain allowlist.
• signaturePublickey: RSA public key used to verify signed profile properties.

Metadata responses are sent with no-cache headers. After signing key rotation, clients should fetch metadata again instead of verifying new profile properties with an old cached key.

Authserver

POST /api/yggdrasil/authserver/authenticate
POST /api/yggdrasil/authserver/refresh
POST /api/yggdrasil/authserver/validate
POST /api/yggdrasil/authserver/invalidate
POST /api/yggdrasil/authserver/signout

These endpoints handle launcher login, token refresh, validation, invalidation, and signout.

authenticate supports:

• Email/account identifier login.
• Profile-name login when yggdrasil_allow_profile_name_login = true.
• clientToken supplied by the client; generated by the server when omitted.
• selectedProfile in the login result.

Sessionserver

POST /api/yggdrasil/sessionserver/session/minecraft/join
GET  /api/yggdrasil/sessionserver/session/minecraft/hasJoined
GET  /api/yggdrasil/sessionserver/session/minecraft/profile/{uuid}

join is called by the Minecraft client with access token, selected profile, and serverId.

hasJoined is called by the Minecraft server with username, serverId, and optional ip. Successful responses include signed profile properties for server-side verification.

profile/{uuid} queries profile properties. When unsigned=false, profile properties are signed; the default unsigned behavior remains protocol compatible.

Profile Lookup

POST /api/yggdrasil/api/profiles/minecraft

Looks up profiles by profile name. The request body is an array of names, and the response follows the protocol shape.

Texture API

PUT    /api/yggdrasil/api/user/profile/{uuid}/{skin|cape}
DELETE /api/yggdrasil/api/user/profile/{uuid}/{skin|cape}
GET    /api/yggdrasil/textures/{hash}

Upload and delete require a valid access token. Public reads return the processed PNG directly by hash.

Protocol Errors

Yggdrasil protocol endpoints do not return:

{ "code": "success", "msg": "", "data": {} }

They return protocol-compatible error bodies, for example:

{
  "error": "ForbiddenOperationException",
  "errorMessage": "Invalid token."
}

Only /api/v1 admin and site APIs use the project envelope.