Mojang API

Mojang API是Mojang提供的应用程序编程接口，允许用户使用自编程序检索玩家数据，它适用于第三方启动器开发人员、服务器运营商和插件开发人员。

所有查询目前限制为每10分钟600次。对于没有购买游戏的注册账户，也可以进行部分信息的查询。

服务器的请求与响应

服务器能接受很多请求，如果没有特殊说明，对于具有负载的请求服务器有下面的限制：

请求头中的Content-Type必须是application/json。如果不是，服务器将返回HTTP状态码415。
如果请求中要求负载，则负载必须是一个有效的JSON文本。如果不是，服务器将返回HTTP状态码400。

如果请求成功，服务器会做出如下的响应：

一个成功的HTTP状态码（2XX）。
返回一个空的负载（这时服务器返回状态码204）或是一个JSON文本。

如果请求失败，服务器会返回一个非2XX的HTTP状态码并返回形式如下方的负载：

根标签
- error：对于错误的简短介绍。
- errorMessage：错误信息。
- cause：错误原因。

下面列出了一些常见的错误，在下文中不再重复说明。

HTTP状态码	错误（error）	错误具体信息（errorMessage）	错误说明
400	IllegalArgumentException	（与具体API有关）	请求中包含了错误或无效的参数。
	MismatchedInputException		请求负载中的JSON文本不满足API要求的格式或请求负载不是有效的JSON文本。
	JsonParseException		请求负载中的JSON文本不满足API要求的格式或请求负载不是有效的JSON文本。
401	（返回空负载）	（返回空负载）	API要求使用访问令牌，但是请求头中没有包含`Authorization`或请求中的访问令牌无效。
401	Unauthorized	The request requires user authentication	API要求使用访问令牌，但是请求头中没有包含`Authorization`。
403	ForbiddenOperationException	Forbidden	访问令牌无效。
404	Not Found	The server has not found anything matching the request URI	服务器找不到请求的URI。
405	Method Not Allowed	The method specified in the request is not allowed for the resource identified by the request URI	接收到了错误请求方法的请求。
415	Unsupported Media Type	The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method	不支持的媒体类型，即请求头`Content-Type`不是API要求的类型。

获取玩家信息

获取玩家信息的API都不需要身份验证得到的访问令牌，部分API可以查询没有购买游戏的注册账户。

获取玩家的UUID

输入

玩家的名称（不区分大小写）。

GET请求

https://api.mojang.com/users/profiles/minecraft/<玩家名称>
https://api.minecraftservices.com/minecraft/profile/lookup/name/<玩家名称>

响应

根标签
- id：玩家的UUID。
- name：正确大写的玩家名称。
- legacy：如果此账户没有迁移到Mojang账户，输出中包含此项。
- demo：如果是没有购买游戏的注册账户，输出中包含此项。

示例

https://api.mojang.com/users/profiles/minecraft/jeb_
提供玩家jeb_的UUID。

 {
   "name": "jeb_",
   "id": "853c80ef3c3749fdaa49938b674adae6"
 }

错误信息

如果没有命名为这个名字的玩家，返回HTTP状态码404。

批量获取玩家UUID

负载

一个存储小于10个的玩家名称字符串的JSON列表，玩家名称不区分大小写。

POST请求

https://api.mojang.com/profiles/minecraft

响应

给定玩家的所有UUID列表。对于不存在的玩家名称，将不返回任何结果。
- 玩家名称。
  - id：玩家的UUID。
  - name：正确大小写的玩家名称。
  - legacy：如果此账户没有迁移到Mojang账户，输出中包含此项。
  - demo：如果是没有购买游戏的注册账户，输出中包含此项。

示例

发送["jeb_","notch"]。

 [
   {
     "id": "853c80ef3c3749fdaa49938b674adae6",
     "name": "jeb_"
   },
   {
     "id": "069a79f444e94726a5befca90e38aaf5",
     "name": "Notch"
   }
 ]

错误信息

HTTP状态码	错误（error）	错误具体信息（errorMessage）	错误说明
400	CONSTRAINT_VIOLATION	size must be between 1 and 10	请求负载的JSON列表为空。
		size must be between 1 and 10	请求负载的JSON列表中元素数量大于10个。
		Invalid profile name	请求负载的JSON列表中含有空字符串。

获取玩家名称

输入

玩家的UUID。

GET请求

https://api.minecraftservices.com/minecraft/profile/lookup/<UUID>

响应

同获取玩家UUID。

示例

https://api.minecraftservices.com/minecraft/profile/lookup/853c80ef3c3749fdaa49938b674adae6
返回如下结果：

{
  "id" : "853c80ef3c3749fdaa49938b674adae6",
  "name" : "jeb_"
}

错误信息

HTTP状态码	错误（error）	错误具体信息（errorMessage）	错误说明
404	NOT_FOUND	Not Found	此UUID不代表任何玩家。
400	CONSTRAINT_VIOLATION	Invalid UUID string: <输入的参数>	URI中的UUID无效。

获取玩家的皮肤和披风

输入

玩家的UUID以及签名的请求。可以在一分钟后最早重复对给定UUID的查询。

GET请求

https://sessionserver.mojang.com/session/minecraft/profile/<UUID> 或
https://sessionserver.mojang.com/session/minecraft/profile/<UUID>?unsigned=false

响应

根标签
- id：玩家的UUID。
- name：正确大写的玩家名称。
- legacy：如果这个账户是一个旧的Minecraft账户，这项才存在。
- properties：玩家属性的列表。
  - name：玩家属性的名称。到目前为止只有textures（玩家纹理）这一属性。
  - signature：只有在请求unsigned=false时，使用Yggdrasil私钥的签名才会作为Base64字符串传递。
  - value：Base64字符串，其中包含玩家所有的纹理（皮肤和披风）。解码后的字符串内容如下：
    - 纹理对象。
      - timestamp：Unix时间戳，以毫秒为单位，时间为调用纹理数据的时间。
      - profileId：玩家的UUID，不带连字符。
      - profileName: 玩家名称。
      - signatureRequired: 只有在请求unsigned=false时才存在。
      - textures：纹理。
        SKIN：皮肤纹理。如果这名玩家没有自定义皮肤，这项不存在。
        url：皮肤纹理的URL链接。
        
        metadata：可选。皮肤的元数据。
        model：固定值slim。当皮肤模型为Alex时这一项才存在，模型为Steve则无该元数据。
        
        CAPE：披风纹理。如果这名玩家没有披风，这项不存在。
        url：披风纹理的URL链接。默认没有披风，仅当Mojang在玩家的账户数据中输入了披风时，才会显示披风。

示例

https://sessionserver.mojang.com/session/minecraft/profile/853c80ef3c3749fdaa49938b674adae6
返回如下结果：

 {
   "id": "853c80ef3c3749fdaa49938b674adae6",
   "name": "jeb_",
   "properties":
   [
     {
       "name": "textures",
       "value": "ewogICJ0aW1lc3R..."
     }
   ]
 }

其中value使用Base64解码之后的内容为：

{
  "timestamp" : 1653838459263,
  "profileId" : "853c80ef3c3749fdaa49938b674adae6",
  "profileName" : "jeb_",
  "textures" : {
    "SKIN" : {
      "url" : "http://textures.minecraft.net/texture/7fd9ba42a7c81eeea22f1524271ae85a8e045ce0af5a6ae16c6406ae917e68b5"
    },
    "CAPE" : {
      "url" : "http://textures.minecraft.net/texture/9e507afc56359978a3eb3e32367042b853cddd0995d17d0da995662913fb00f7"
    }
  }
}

错误信息

HTTP状态码	错误（error）	错误具体信息（errorMessage）	错误说明
204	（返回空负载）	（返回空负载）	此UUID不代表任何玩家。
400	（无）	Not a valid UUID: <输入的参数>	URI中的UUID无效。

Microsoft身份验证

该过程包含多个步骤并且需要不同的令牌，但最终会获取到一个标准的Minecraft令牌。目前所有的账户均已启用这一新的验证系统。

在使用Microsoft验证之前，必须要先通过创建Microsoft Azure应用程序来获得OAuth 2.0客户端ID（无需获取密钥）；之后根据这篇支持文档，还需填写此表单以申请API访问权限，否则使用api.minecraftservices.com域名下的任意API时都只会返回403。之后，就可以获取Microsoft令牌。

请注意：在获取令牌时，tenant参数必须为consumers，scope参数中必须包含XboxLive.signin，否则无法进行获取Xbox Live令牌等操作。

使用Microsoft令牌获取Xbox Live令牌

负载

根标签
- Properties：验证属性。
  - AuthMethod：登录方法。固定值RPS。
  - SiteName：网站名称。固定值user.auth.xboxlive.com。
  - RpsTicket：登录使用的票据。值为d=<Microsoft访问令牌>。
- RelyingParty：依赖的平台。固定值http://auth.xboxlive.com。
- TokenType：访问令牌的类型。固定值JWT。

POST请求

https://user.auth.xboxlive.com/user/authenticate

要求SSL实现支持SSL重协商。

响应

根标签
- IssueInstant：获取Xbox Live令牌的时间。
- NotAfter：Xbox Live令牌过期时间。
- Token：Xbox Live访问令牌。
- DisplayClaims：未知。
  - xui：未知。
    - - uhs：用户的哈希码。

使用Xbox Live令牌获取XSTS令牌

负载

根标签
- Properties：验证属性。
  - SandboxId：沙盒ID。固定值RETAIL。
  - UserTokens：用户的Xbox Live令牌。
    - ：用户的Xbox Live令牌，在上一步获取。
- RelyingParty：依赖的平台。固定值rp://api.minecraftservices.com/。
- TokenType：访问令牌的类型。固定值JWT。

POST请求

https://xsts.auth.xboxlive.com/xsts/authorize

要求SSL实现支持SSL重协商。

响应

根标签
- IssueInstant：获取XSTS令牌的时间。
- NotAfter：XSTS令牌过期时间。
- Token：XSTS访问令牌。
- DisplayClaims：未知。
  - xui：未知。
    - - uhs：用户的哈希码。

错误信息

如果没有成功获取XSTS令牌，服务器返回HTTP状态码401。

通过XSTS令牌获取Minecraft访问令牌

负载

根标签
- identityToken：身份令牌。值为XBL3.0 x=<用户哈希码>;<XSTS访问令牌>。

POST请求

https://api.minecraftservices.com/authentication/login_with_xbox

响应

根标签
- username：一个UUID，但不是账户的UUID。
- roles：未知，为空。
- access_token：Minecraft访问令牌。
- token_type：令牌类型。固定值Bearer。
- expires_in：有效时间，以秒为单位。

验证账户是否拥有Minecraft

请求头

Authorization要求为Bearer <有效的Minecraft访问令牌>。

GET请求

https://api.minecraftservices.com/entitlements/mcstore

响应

如果账户拥有Minecraft，服务器将会返回下面的负载：

根标签
- items：数据和签名列表。
  - name：数据名称，product_minecraft或game_minecraft。
  - signature：数据的JWT签名。
- signature：JWT签名。
- keyID：未知。

如果账户不拥有Minecraft或者是XGP用户，服务器将返回空负载。

玩家配置操作

操作玩家配置的API基本都在https://api.minecraftservices.com服务器下，并且都要求请求头包含Authorization，且值为Bearer <有效的Minecraft访问令牌>。如果请求头不包含访问令牌信息或者访问令牌无效，服务器将返回HTTP状态码401。

获取配置信息

GET请求

/minecraft/profile

响应

根标签
- id：玩家的UUID。
- name：玩家名称。
- skins：玩家拥有的所有皮肤信息。
  - ：一个皮肤。
    - id：皮肤的UUID。
    - state：皮肤的使用状态。
    - url：皮肤的URL。
    - variant：皮肤类型。如果是Steve模型的皮肤这一项是CLASSIC，如果是Alex模型的皮肤这一项是SLIM。
- capes：玩家拥有的所有披风信息。
  - ：一个披风。
    - id：披风的UUID。
    - state：披风的使用状态。
    - url：披风的URL。
    - alias：披风的别名。

获取玩家属性

GET请求

/player/attributes

响应

根标签
- privileges：玩家的能力。
  - onlineChat：玩家接受聊天信息的能力。
    - enable：为真时玩家可以接受聊天信息，为假时不能。
  - multiplayerServer：玩家加入多人服务器的能力。
    - enable：为真时玩家可以加入多人服务器，为假时不能。
  - multiplayerRealms：玩家加入Realms的能力。
    - enable：为真时玩家可以加入Realms，为假时不能。
  - telemetry：玩家发送遥测数据的能力。
    - enable：为真时玩家可以发送遥测数据。
  - optionalTelemetry：玩家发送可选遥测数据的能力。
    - enable：为真时玩家可以发送可选遥测数据。
- profanityFilterPreferences：玩家Realms聊天过滤选项。
  - profanityFilterOn：是否开启Realms聊天过滤。
- banStatus：玩家封禁状态。
  - bannedScopes：玩家封禁的范围。
    - ：玩家的封禁范围对象。如果玩家未被封禁，则不存在这些对象。目前只有MULTIPLAYER项。
      - banId：封禁的UUID。
      - expires：封禁到期时间。如果玩家被永久封禁，这一项不存在。
      - reason：封禁原因。
      - reasonMessage：封禁消息。

启用/禁用Realms聊天过滤

负载

根标签
- profanityFilterPreferences：玩家Realms聊天过滤选项。
  - profanityFilterOn：是否开启Realms聊天过滤。

POST请求

/player/attributes

响应

与获取玩家属性的响应相同。

获取屏蔽玩家列表

GET请求

/privacy/blocklist

响应

根标签
- blockedProfiles：被屏蔽的玩家列表。这些玩家的聊天信息和Realms邀请将不可见。
  - ：被屏蔽玩家的UUID。

获得签名密钥对

POST请求

/player/certificates

响应

根标签
- keyPair：签名使用的密钥对。
  - privateKey：私钥。以-----BEGIN RSA PRIVATE KEY-----开头并以-----END RSA PRIVATE KEY-----结束。
  - publicKey：公钥。以-----BEGIN RSA PUBLIC KEY-----开头并以-----END RSA PUBLIC KEY-----结束。
- publicKeySignature：在刚加入签名时使用的公钥签名。目前最新版本已经不再使用此签名，而是V2版本的签名。
- publicKeySignatureV2：公钥签名。
- expiresAt：密钥对到期时间。
- refreshedAfter：密钥对刷新时间。

获取玩家名称信息

GET请求

/minecraft/profile/namechange

响应

根标签
- changedAt：最近一次的名称修改时间。
- createdAt：玩家配置创建的时间。
- nameChangeAllowed：是否允许修改名称。

检查礼品卡是否有效

GET请求

/productvoucher/giftcode

响应

如果礼品卡有效，服务器会返回HTTP状态码200或者204。如果礼品卡无效，服务器将会返回HTTP状态码404。

检查名称可用性

GET请求

/minecraft/profile/name/<要检查的名称>/available

响应

根标签
- status：名称的状态。如果是DUPLICATE代表名称已被占用，如果是AVAILABLE代表名称可用，如果是NOT_ALLOWED代表名称不符合要求。

修改名称

输入

修改的名称。

PUT请求

/minecraft/profile/name/<修改的名称>

响应

根标签
- id：玩家的UUID。
- name：修改之后的玩家名称。
- skins：玩家拥有的所有皮肤信息。
  - ：一个皮肤。
    - id：皮肤的UUID。
    - state：皮肤的使用状态。
    - url：皮肤的URL。
    - variant：皮肤类型。如果是Steve模型的皮肤这一项是CLASSIC，如果是Alex模型的皮肤这一项是SLIM。
- capes：玩家拥有的所有披风信息。
  - ：一个披风。
    - id：披风的UUID。
    - state：披风的使用状态。
    - url：披风的URL。
    - alias：披风的别名。

错误信息

HTTP状态码	错误（error）	错误具体信息（errorMessage）	错误说明
400	CONSTRAINT_VIOLATION	changeProfileName.profileName: Invalid profile name	名称不符合要求（大于16个字符或含有非数字、字母和下划线的字符）。
403	（无）	Could not change name for profile	不可以修改名称。如果`detail.status`是`DUPLICATE`说明此名称已被占用。
429	-	-	发送了太多次改名请求。

更换皮肤

负载

根标签
- variant：皮肤模型。如果是Steve模型要使用classic，如果是Alex模型要使用slim。
- url：皮肤的URL。

POST请求

/minecraft/profile/skins

响应

如果更换成功，服务器将返回空负载。

上传皮肤

负载

负载由两部分组成。

variant：皮肤模型。如果是Steve模型要使用classic，如果是Alex模型要使用slim。
file：图片数据。在上传之后会将玩家的皮肤设置为新上传的这个皮肤。

POST请求

/minecraft/profile/skins

举例

curl -X POST -H "Authorization: Bearer <access token>" -F variant=classic -F file="@steeevee.png;type=image/png" https://api.minecraftservices.com/minecraft/profile/skins

响应

如果上传成功，服务器将返回空负载。

重置皮肤

输入

玩家的UUID。

DELETE请求

/minecraft/profile/skins/active

响应

如果操作成功，服务器将返回HTTP状态码200。

隐藏披风

DELETE请求

/minecraft/profile/capes/active

响应

如果操作成功，服务器将返回空负载。

显示披风

负载

根标签
- capeId：要显示的披风的UUID。

PUT请求

/minecraft/profile/capes/active

响应

根标签
- id：玩家的UUID。
- name：玩家名称。
- skins：玩家拥有的所有皮肤信息。
  - ：一个皮肤。
    - id：皮肤的UUID。
    - state：皮肤的使用状态。
    - url：皮肤的URL。
    - variant：皮肤类型。如果是Steve模型的皮肤这一项是CLASSIC，如果是Alex模型的皮肤这一项是SLIM。
- capes：玩家拥有的所有披风信息。
  - ：一个披风。
    - id：披风的UUID。
    - state：披风的使用状态。
    - url：披风的URL。
    - alias：披风的别名。

错误信息

HTTP状态码	错误（error）	错误具体信息（errorMessage）	错误说明
400	（无）	profile does not own cape	玩家没有指定的披风。

好友操作

此段落需要更新。

段落中某些信息可以参照英文版进行翻译更新。
附加信息：该部分内容存在错误和信息缺失，在该完成修订前，建议首先参考英文 Minecraft Wiki 中的对应内容。

好友操作的API都在https://api.minecraftservices.com服务器下，且与玩家配置操作一样都要求请求头包含Authorization，且值要求为Bearer <有效的Minecraft访问令牌>。如果请求头不包含访问令牌信息或者访问令牌无效，服务器将返回HTTP状态码401。

好友操作有请求频率限制。在上一条请求发出后，10秒内不能再次请求好友操作API，否则服务器将以HTTP状态码429拒绝请求。同步在线状态API则没有请求频率限制。

获取好友列表

GET请求

/friends

你也可以发送一个可选的If-None-Match请求头，详见下文。

响应

根标签
- friends：已添加的好友列表。
  - ：一条好友信息。
    - profileId：玩家档案ID。
    - name：玩家名称。
- incomingRequests：好友申请列表。
  - ：一条好友信息。
    - profileId：玩家档案ID。
    - name：玩家名称。
- outgoingRequests：好友请求列表。
  - ：一条好友信息。
    - profileId：玩家档案ID。
    - name：玩家名称。
- empty：无作用。

响应会带有Etag返回头，在接下来的请求中，可以被保存并作为If-None-Match请求头的值重复使用。

如果自上一次请求后，好友列表没有改变，且If-None-Match请求头的值与上一次请求的Etag返回头相同，Mojang服务器会返回HTTP 304 Not Modified响应。

示例

{
    "friends": [
        {
            "profileId": "61699b2ed3274a019f1e0ea8c3f06bc6",
            "name": "Dinnerbone"
        }
    ],
    "incomingRequests": [
        {
            "profileId": "853c80ef3c3749fdaa49938b674adae6",
            "name": "jeb_"
        }    
    ],
    "outgoingRequests": [
        {
            "profileId": "069a79f444e94726a5befca90e38aaf5",
            "name": "Notch"
        }
    ],
    "empty": false
}

调整玩家列表

PUT请求

/friends

负载

根标签
- updateType：操作类型。可以为ADD（添加好友：包括发送好友请求和接受他人请求）或REMOVE（移除好友：包括删除好友和拒绝他人请求）。
- name：玩家名称。游戏仅在添加好友时使用此字段。
- profileId：玩家档案UUID。

name和profileId是可选的，但至少提供一个。如果同时提供，则profileId被优先考虑。

示例

{
    "profileId": "069a79f444e94726a5befca90e38aaf5",
    "updateType": "ADD"
}

响应

与§ 获取好友列表相同。

错误信息

根标签
- path: 请求的地址。对于此API，其总为/friends。
- details:
  - status: HTTP状态码。详见下方表格。
- errorMessage: 错误具体信息。

HTTP状态码	`details.status`	`errorMessage`(错误具体信息)	Explanation(错误说明)
400	UNKNOWN_PROFILE	Name or profile does not exist	名称或档案不存在。
	CANNOT_ADD_SELF	Cannot add yourself as friend	不能将自己添加为好友。
	NOT_FRIENDS	Not friend with `profileId` cannot remove	`profileId`不是当前玩家的好友，不能被删除好友。
	ALREADY_FRIENDS	Already friend with `profileId`	`profileId`已经是当前玩家的好友，添加好友。
	INVALID_JSON	与具体的请求有关	所有必须的参数都在请求中，但解码失败。(例如错误的列举值，无效的玩家档案ID)
	CONSTRAINT_VIOLATION	与具体的请求有关	一些请求的参数丢失。
403	INVITE_REJECTED	User does not have friends enabled or accept invites	用户未启用好友列表或接受邀请。

同步在线状态

此API用于查询好友在线状态和同步玩家当前状态，没有用于单独查询好友在线状态的API。

POST请求

/presence

负载

根标签
- status：当前玩家状态。可选值包括：ONLINE（在线）、PLAYING_OFFLINE（单人游戏中）、PLAYING_REALMS（Realm游戏中）、PLAYING_SERVER（多人游戏中）、PLAYING_HOSTED_SERVER（作为主机进行多人游戏中）和OFFLINE（离线）。
- joinInfo：玩家加入多人世界的信息。
  - value：固定值null。
  - invites：已邀请的玩家列表。
    - ：玩家档案的UUID。

对于所有在线状态，可以选择省略整个joininfo对象，即使在同步PLAYING_HOSTED_SERVER状态时也是如此，在这种情况下，好友的游戏客户端不会显示“加入”按钮。

要同步ONLINE、OFFLINE、PLAYING_OFFLINE和PLAYING_SERVER状态，必须提供一个字符串（长度大于等于1小于等于256）或数字类型的joininfo.value对象，或省略整个joininfo对象，否则Mojang服务器将返回HTTP 400 Bad Request响应。

要同步PLAYING_HOSTED_SERVER状态，必须提供一个值为null的joinInfo.value对象，或省略整个joininfo对象，否则Mojang服务器将返回HTTP 400 Bad Request响应。

要同步PLAYING_REALMS状态，必须提供一个数字类型的joinInfo.value对象，或省略整个joininfo对象，否则Mojang服务器将返回HTTP 400 Bad Request响应。

可以将非好友（甚至是虚拟 UUID，例如全零）加入到joinInfo.value对象中，Mojang服务器不会返回错误，然而由于不是好友，玩家不会出现在他们的好友列表中，因此他们不会收到你的点对点联机邀请。

响应

根标签
- presence: 在线玩家列表。服务器仅返回在线玩家列表。
  - : 一条在线玩家信息。
    - profileId: 玩家档案UUID，带破折号。
    - pmid: PMID 用于点对点联机，编码在玩家访问令牌中，UUID带有破折号。
    - status: 玩家状态，可选值与上文中可选值一致。
    - joinInfo: 在某些情况下被省略，见下文。
      - value: 通常与PMID相同，但也可以是其他值。
      - invited: 是否被邀请进入点对点联机会话。
    - lastUpdated: 玩家上一次同步状态时的时间戳。

如果好友在报告其在线状态时省略了joinInfo，那么响应中的joinInfo也会被省略，这在原版Minecraft客户端中不应发生。

在大多数情况下，joinInfo.value应与PMID相同，但如果好友在报告在线状态时发送了非空值，它也可能是其他东西。这在原版Minecraft客户端中不应发生。这个键的含义尚不明确，因为游戏客户端会忽略它。

当在线状态为OFFLINE时，joinInfo.invited可能为true，这意味着好友在其在线选项中设置了 “在线状态可见性:仅展示部分”。这会将状态限制为仅报告ONLINE或OFFLINE，同时仍允许他们邀请其他人加入其点对点联机会话。

目前，游戏客户端在关闭前似乎不会报告OFFLINE状态，10分钟后，由于缺少在线状态更新，服务器将认为该玩家已离线。

此API将始终返回好友同步的最新在线状态。也就是说，如果同时运行两个游戏实例，可能会发生竞争，因为两个实例都在尝试同步其在线状态。而好友会看到哪个在线状态取决于他们的客户端何时同步其在线状态。

所有可用的在线状态


`status`（在线状态）	UI上显示的文本	解释	额外
OFFLINE	离线	玩家离线。	离线玩家不会出现在好友同步在线状态的响应中。
ONLINE	在线	玩家在线但没有游玩任何一个世界或服务器 (例如停留在主菜单上，调整设置等)。	如果玩家在在线选项中设置了"在线状态可见性: 仅展示部分" ，游戏将只同步此在线状态。
PLAYING_OFFLINE	在线（世界）	玩家正在游玩一个没有开启点对点联机的世界(多人游戏被设置为"关"或"局域网")。
PLAYING_HOSTED_SERVER	在线（世界）	玩家正在游玩一个开启点对点联机的世界并且允许他人进入。	好友列表中会显示“加入”按钮
PLAYING_REALMS	在线（Realm）	玩家正在游玩一个Realms服务器。	当前游戏客户端不会同步此状态。
PLAYING_SERVER	在线（服务器）	玩家正在游玩一个第三方服务器。	当前游戏客户端不会同步此状态。

错误消息

与§ 调整玩家列表几乎相同，只有INVALID_JSON和CONSTRAINT_VIOLATION存在。如果请求中包含joinInfo.value但违反了上述规则，Mojang服务器会返回HTTP 400 Bad Request响应，响应中只包含path和errorMessage。

示例请求

{
  "status": "PLAYING_HOSTED_SERVER",
  "joinInfo": {
    "value": null,
    "invites": [
      "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "853c80ef-3c37-49fd-aa49-938b674adae6",
      "61699b2e-d327-4a01-9f1e-0ea8c3f06bc6"
    ]
  }
}

示例响应

{
  "presence": [
    {
      "profileId": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "pmid": "c41da2ff-0874-4bbe-a28b-d122bc467b1f",
      "status": "ONLINE",
      "lastUpdated": "2026-05-15T19:25:58Z"
    },
	{
      "profileId": "853c80ef-3c37-49fd-aa49-938b674adae6",
      "pmid": "87c83220-965c-4d65-867f-8718f5ba04a6",
      "status": "ONLINE",
	  "joinInfo": {
	    "value": "87c83220-965c-4d65-867f-8718f5ba04a6",
		"invited": true
	  },
      "lastUpdated": "2026-05-15T19:26:12Z"
    },
	{
      "profileId": "61699b2e-d327-4a01-9f1e-0ea8c3f06bc6",
      "pmid": "f289feed-30ab-4039-bef8-5752ea9d2c1c",
      "status": "PLAYING_HOSTED_SERVER",
	  "joinInfo": {
	    "value": "f289feed-30ab-4039-bef8-5752ea9d2c1c",
		"invited": false
	  },
      "lastUpdated": "2026-05-15T19:26:32Z"
    }
  ]
}

服务器操作

获取屏蔽服务器信息

GET请求

https://sessionserver.mojang.com/blockedservers

响应

服务器将返回一个文本，每一行都是被屏蔽的服务器的哈希码。

客户端登录验证

负载

根标签
- accessToken：有效的Minecraft访问令牌。
- selectedProfile：不带有连字符的玩家UUID。
- serverId：服务器的ID。

其中服务器的ID由下方算法计算而成：

public static String generateServerId(String baseServerId,   // 服务器的基础ID，通常为空字符串""
                                      PublicKey publicKey,   // 服务器的RSA公钥
                                      SecretKey secretKey    // 服务器与客户端之间使用的对称加密AES密钥
                                     ) throws Exception { 
    MessageDigest messageDigest = MessageDigest.getInstance("SHA-1");
    messageDigest.update(baseServerId.getBytes("ISO_8859_1"));
    messageDigest.update(secretKey.getEncoded());
    messageDigest.update(publicKey.getEncoded());
    byte[] digestData = messageDigest.digest();
    return new BigInteger(digestData).toString(16);
}

POST请求

https://sessionserver.mojang.com/session/minecraft/join

响应

如果验证成功，服务器返回HTTP状态码204。

服务器登录验证

输入

不区分大小写的玩家名称、由上方算法得出的服务器ID和客户端IP（可选）。

GET请求

https://sessionserver.mojang.com/session/minecraft/hasJoined?username=<玩家名称>&serverId=<服务器ID>&ip=<客户端IP>

响应

如果验证成功，服务器将返回和上方获取玩家的皮肤和披风一样的负载。

历史

2014年4月14日							Mojang API发布。
2020年11月							获取玩家UUID的API不再支持at参数。
2021年10月8日							查询Mojang API状态的API被移除。在此之前，此API为`https://status.mojang.com/check`。
2022年5月8日							获取销量统计数据的API被移除。在此之前，此API为`https://api.mojang.com/orders/statistics`。
2022年9月13日							查询玩家历史名称的API被移除。在此之前，此API为`https://api.mojang.com/user/profiles/<UUID>/names`。