Minecraft:Mojang API: Difference between revisions
More actions
Sync: new page from Minecraft |
Fix template calls: add MC/ prefix |
||
| (One intermediate revision by the same user not shown) | |||
| Line 1: | Line 1: | ||
This page provides documentation for '''API''' endpoints provided by | This page provides documentation for '''API''' endpoints provided by Mojang Studios which allows user to query player data and make changes programmatically. | ||
Most of the API has a per-IP ratelimit of 200 requests per 2 minutes. For IPv6, the ratelimits are bucketed by /56 subnet. Some endpoints have different ratelimits. | Most of the API has a per-IP ratelimit of 200 requests per 2 minutes. For IPv6, the ratelimits are bucketed by /56 subnet. Some endpoints have different ratelimits. | ||
| Line 18: | Line 18: | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}}: Root tag. | * {{MC/Nbt|compound}}: Root tag. | ||
** {{Nbt|string|error}}: Error identifier | ** {{MC/Nbt|string|error}}: Error identifier | ||
** {{Nbt|string|errorMessage}}: Description of the error | ** {{MC/Nbt|string|errorMessage}}: Description of the error | ||
** {{Nbt|string|cause}}: Description of the cause of the error | ** {{MC/Nbt|string|cause}}: Description of the cause of the error | ||
</div> | </div> | ||
| Line 28: | Line 28: | ||
{| class="wikitable mw-collapsible mw-collapsed" | {| class="wikitable mw-collapsible mw-collapsed" | ||
! HTTP status code | ! HTTP status code | ||
! {{ | ! {{MC/Cd|error}} | ||
! {{ | ! {{MC/Cd|errorMessage}} | ||
! Explanation | ! Explanation | ||
|- | |- | ||
| Line 56: | Line 56: | ||
| Invalid auth token. | | Invalid auth token. | ||
|- | |- | ||
| {{ | | {{MC/Tc|n/a}} | ||
| Your account has been suspended. Please contact customer service. | | Your account has been suspended. Please contact customer service. | ||
| Account has been banned/suspended state by triggering a high volume of erroneous requests. See [[#Account suspensions]]. | | Account has been banned/suspended state by triggering a high volume of erroneous requests. See [[#Account suspensions]]. | ||
| Line 73: | Line 73: | ||
| Unsupported Media Type | | 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 | | 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 | ||
| {{ | | {{MC/Cd|Content-Type}} request header does not match the type the endpoint allows. | ||
|} | |} | ||
| Line 115: | Line 115: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|id}}: [[Minecraft:UUID]] of the player. | ** {{MC/Nbt|string|id}}: [[Minecraft:UUID]] of the player. | ||
** {{Nbt|string|name}}: Name of the player, case sensitive. | ** {{MC/Nbt|string|name}}: Name of the player, case sensitive. | ||
** {{Nbt|bool|legacy}}: Included in response if the account has not migrated to Mojang account. | ** {{MC/Nbt|bool|legacy}}: Included in response if the account has not migrated to Mojang account. | ||
** {{Nbt|bool|demo}}: Included in response if the account does not own the game. | ** {{MC/Nbt|bool|demo}}: Included in response if the account does not own the game. | ||
</div> | </div> | ||
| Line 158: | Line 158: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|list}} The UUID list for all the players. For players that does not exist, no result is returned. | * {{MC/Nbt|list}} The UUID list for all the players. For players that does not exist, no result is returned. | ||
** {{Nbt|compound}} Player name. | ** {{MC/Nbt|compound}} Player name. | ||
*** {{Nbt|string|id}}: [[Minecraft:UUID]] of the player. | *** {{MC/Nbt|string|id}}: [[Minecraft:UUID]] of the player. | ||
*** {{Nbt|string|name}}: Name of the player, case sensitive. | *** {{MC/Nbt|string|name}}: Name of the player, case sensitive. | ||
*** {{Nbt|bool|legacy}}: Included in response if the account has not migrated to Mojang account. | *** {{MC/Nbt|bool|legacy}}: Included in response if the account has not migrated to Mojang account. | ||
*** {{Nbt|bool|demo}}: Included in response if the account does not own the game. | *** {{MC/Nbt|bool|demo}}: Included in response if the account does not own the game. | ||
</div> | </div> | ||
| Line 183: | Line 183: | ||
{| class="wikitable mw-collapsible mw-collapsed" | {| class="wikitable mw-collapsible mw-collapsed" | ||
! HTTP status code | ! HTTP status code | ||
! {{ | ! {{MC/Cd|error}} | ||
! {{ | ! {{MC/Cd|errorMessage}} | ||
! Explanation | ! Explanation | ||
|- | |- | ||
| Line 201: | Line 201: | ||
; Input | ; Input | ||
Player UUID and whether the request is | Player UUID and whether the request is signed. | ||
; Request (GET) | ; Request (GET) | ||
| Line 210: | Line 210: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|id}}: Player's [[Minecraft:UUID]]. | ** {{MC/Nbt|string|id}}: Player's [[Minecraft:UUID]]. | ||
** {{Nbt|string|name}}: Player name, case sensitive. | ** {{MC/Nbt|string|name}}: Player name, case sensitive. | ||
** {{Nbt|boolean|legacy}}: Included in response if the account has not migrated to Mojang account. | ** {{MC/Nbt|boolean|legacy}}: Included in response if the account has not migrated to Mojang account. | ||
** {{Nbt|list|properties}}: A list of player properties. | ** {{MC/Nbt|list|properties}}: A list of player properties. | ||
*** {{Nbt|string|name}}: Name of the property. For now, the only property that exists is <code>textures</code>. | *** {{MC/Nbt|string|name}}: Name of the property. For now, the only property that exists is <code>textures</code>. | ||
*** {{Nbt|string|signature}}: Signature signed with <samp>Yggdrasil</samp> private key as Base64 string, only exists when <code>unsigned=false</code>. | *** {{MC/Nbt|string|signature}}: Signature signed with <samp>Yggdrasil</samp> private key as Base64 string, only exists when <code>unsigned=false</code>. | ||
*** {{Nbt|string|value}}: | *** {{MC/Nbt|string|value}}: Base64 string with all player textures (skin and cape). The decoded string includes: | ||
**** {{Nbt|compound}} Texture object. | **** {{MC/Nbt|compound}} Texture object. | ||
***** {{Nbt|int|timestamp}} | ***** {{MC/Nbt|int|timestamp}}: Unix time in milliseconds the texture is accessed. | ||
***** {{Nbt|string|profileId}}: Player's UUID without dashes. | ***** {{MC/Nbt|string|profileId}}: Player's UUID without dashes. | ||
***** {{Nbt|string|profileName}}: Player name. | ***** {{MC/Nbt|string|profileName}}: Player name. | ||
***** {{Nbt|boolean|signatureRequired}}: Only exists when <code>unsigned=false</code>. | ***** {{MC/Nbt|boolean|signatureRequired}}: Only exists when <code>unsigned=false</code>. | ||
***** {{Nbt|compound|textures}}: Texture. | ***** {{MC/Nbt|compound|textures}}: Texture. | ||
****** {{Nbt|compound|SKIN}} | ****** {{MC/Nbt|compound|SKIN}}: Skin texture. This does not exist if the player does not have a custom skin. | ||
******* {{Nbt|string|url}}: URL to the skin texture. | ******* {{MC/Nbt|string|url}}: URL to the skin texture. | ||
******* {{Nbt|compound|metadata}}: Optional. Metadata for the skin. | ******* {{MC/Nbt|compound|metadata}}: Optional. Metadata for the skin. | ||
******** {{Nbt|string|model}}: <code>slim</code>. Only exists when skin model is <samp>Alex</samp>. When skin model is <samp>Steve</samp>, this metadata does not exist. | ******** {{MC/Nbt|string|model}}: <code>slim</code>. Only exists when skin model is <samp>Alex</samp>. When skin model is <samp>Steve</samp>, this metadata does not exist. | ||
****** {{Nbt|compound|CAPE}} | ****** {{MC/Nbt|compound|CAPE}}: Cape texture. If the player does not have a cape, this does not exist. | ||
******* {{Nbt|string|url}}: URL to the cape texture. | ******* {{MC/Nbt|string|url}}: URL to the cape texture. | ||
</div> | </div> | ||
| Line 246: | Line 246: | ||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Content in {{Nbt|string|value}} after Base64 decoded: | Content in {{MC/Nbt|string|value}} after Base64 decoded: | ||
<syntaxhighlight lang="json"> | <syntaxhighlight lang="json"> | ||
{ | { | ||
| Line 267: | Line 267: | ||
{| class="wikitable mw-collapsible mw-collapsed" | {| class="wikitable mw-collapsible mw-collapsed" | ||
! HTTP status code | ! HTTP status code | ||
! {{ | ! {{MC/Cd|error}} | ||
! {{ | ! {{MC/Cd|errorMessage}} | ||
! Explanation | ! Explanation | ||
|- | |- | ||
| Line 284: | Line 284: | ||
== Microsoft authentication == | == Microsoft authentication == | ||
{{ | {{MC/For|overview on the authentication steps|Microsoft authentication}} | ||
Authentication for Microsoft accounts. Before using Microsoft auth, an [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app Microsoft Azure Application] must be created to obtain [https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow OAuth 2.0] client ID and token, which can then be used to obtain a Microsoft token. When obtaining the token, the {{ | Authentication for Microsoft accounts. Before using Microsoft auth, an [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app Microsoft Azure Application] must be created to obtain [https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow OAuth 2.0] client ID and token, which can then be used to obtain a Microsoft token. When obtaining the token, the {{MC/Cd|scope}} parameter should include {{samp|XboxLive.signin}} to obtain an Xbox Live token. | ||
=== Obtain an Xbox Live token with Microsoft token === | === Obtain an Xbox Live token with Microsoft token === | ||
| Line 292: | Line 292: | ||
; Payload | ; Payload | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|compound|Properties}}: Authentication properties | ** {{MC/Nbt|compound|Properties}}: Authentication properties | ||
*** {{Nbt|string|AuthMethod}}: Login method. This should be <code>RPS</code>. | *** {{MC/Nbt|string|AuthMethod}}: Login method. This should be <code>RPS</code>. | ||
*** {{Nbt|string|SiteName}}: Website name. This should be <code>user.auth.xboxlive.com</code>. | *** {{MC/Nbt|string|SiteName}}: Website name. This should be <code>user.auth.xboxlive.com</code>. | ||
*** {{Nbt|string|RpsTicket}}: Ticket used for logging in. Value should be <code>d=<''Microsoft access token''></code>. | *** {{MC/Nbt|string|RpsTicket}}: Ticket used for logging in. Value should be <code>d=<''Microsoft access token''></code>. | ||
** {{Nbt|string|RelyingParty}}: Replying party. This should be <code>http://auth.xboxlive.com</code>. | ** {{MC/Nbt|string|RelyingParty}}: Replying party. This should be <code>http://auth.xboxlive.com</code>. | ||
** {{Nbt|string|TokenType}}: Type of the access token. This should be <code>JWT</code>. | ** {{MC/Nbt|string|TokenType}}: Type of the access token. This should be <code>JWT</code>. | ||
</div> | </div> | ||
| Line 308: | Line 308: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|IssueInstant}}: Time when obtaining the Xbox Live token. | ** {{MC/Nbt|string|IssueInstant}}: Time when obtaining the Xbox Live token. | ||
** {{Nbt|string|NotAfter}}: Time the Xbox Live token is expired. | ** {{MC/Nbt|string|NotAfter}}: Time the Xbox Live token is expired. | ||
** {{Nbt|string|Token}}: Xbox Live access token. | ** {{MC/Nbt|string|Token}}: Xbox Live access token. | ||
** {{Nbt|compound|DisplayClaims}}: Unknown. | ** {{MC/Nbt|compound|DisplayClaims}}: Unknown. | ||
*** {{Nbt|list|xui}}: Unknown. | *** {{MC/Nbt|list|xui}}: Unknown. | ||
**** {{Nbt|compound}} | **** {{MC/Nbt|compound}} | ||
***** {{Nbt|string|uhs}}: User hashcode. | ***** {{MC/Nbt|string|uhs}}: User hashcode. | ||
</div> | </div> | ||
| Line 322: | Line 322: | ||
; Payload | ; Payload | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|compound|Properties}}: Auth properties. | ** {{MC/Nbt|compound|Properties}}: Auth properties. | ||
*** {{Nbt|string|SandboxId}}: Sandbox ID. This should be <code>RETAIL</code>. | *** {{MC/Nbt|string|SandboxId}}: Sandbox ID. This should be <code>RETAIL</code>. | ||
*** {{Nbt|list|UserTokens}}: User's Xbox Live token. | *** {{MC/Nbt|list|UserTokens}}: User's Xbox Live token. | ||
**** {{Nbt|string}}: User's Xbox Live token obtained in the previous step. | **** {{MC/Nbt|string}}: User's Xbox Live token obtained in the previous step. | ||
** {{Nbt|string|RelyingParty}}: Replying party. This should be <code>rp://api.minecraftservices.com/</code>. | ** {{MC/Nbt|string|RelyingParty}}: Replying party. This should be <code>rp://api.minecraftservices.com/</code>. | ||
** {{Nbt|string|TokenType}}: Type of the access token. This should be <code>JWT</code>. | ** {{MC/Nbt|string|TokenType}}: Type of the access token. This should be <code>JWT</code>. | ||
</div> | </div> | ||
| Line 338: | Line 338: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|IssueInstant}}: Time when obtaining the XSTS token. | ** {{MC/Nbt|string|IssueInstant}}: Time when obtaining the XSTS token. | ||
** {{Nbt|string|NotAfter}}: Time the XSTS token is expired. | ** {{MC/Nbt|string|NotAfter}}: Time the XSTS token is expired. | ||
** {{Nbt|string|Token}}: XSTS access token. | ** {{MC/Nbt|string|Token}}: XSTS access token. | ||
** {{Nbt|compound|DisplayClaims}}: Unknown. | ** {{MC/Nbt|compound|DisplayClaims}}: Unknown. | ||
*** {{Nbt|list|xui}}: Unknown. | *** {{MC/Nbt|list|xui}}: Unknown. | ||
**** {{Nbt|compound}} | **** {{MC/Nbt|compound}} | ||
***** {{Nbt|string|uhs}}: User hashcode. | ***** {{MC/Nbt|string|uhs}}: User hashcode. | ||
</div> | </div> | ||
| Line 355: | Line 355: | ||
; Payload | ; Payload | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|identityToken}}: Identity token. The value should be <code>XBL3.0 x=<''User hashcode''>;<''XSTS access token''></code>. | ** {{MC/Nbt|string|identityToken}}: Identity token. The value should be <code>XBL3.0 x=<''User hashcode''>;<''XSTS access token''></code>. | ||
</div> | </div> | ||
| Line 364: | Line 364: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|username}}: UUID (not the UUID for the player) | ** {{MC/Nbt|string|username}}: UUID (not the UUID for the player) | ||
** {{Nbt|list|roles}}: Unknown, empty. | ** {{MC/Nbt|list|roles}}: Unknown, empty. | ||
** {{Nbt|string|access_token}}: Minecraft access token. | ** {{MC/Nbt|string|access_token}}: Minecraft access token. | ||
** {{Nbt|string|token_type}}: Token type. This is always <code>Bearer</code>. | ** {{MC/Nbt|string|token_type}}: Token type. This is always <code>Bearer</code>. | ||
** {{Nbt|string|expires_in}}: Time period until the token expires in seconds. | ** {{MC/Nbt|string|expires_in}}: Time period until the token expires in seconds. | ||
</div> | </div> | ||
| Line 383: | Line 383: | ||
If the account owns Minecraft, returns: | If the account owns Minecraft, returns: | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|list|items}}: Products licensed to use. | ** {{MC/Nbt|list|items}}: Products licensed to use. | ||
*** {{Nbt|string|name}}: Data name, either <code>product_minecraft</code>, <code>game_minecraft</code>, <code>product_minecraft_bedrock</code> or <code>game_minecraft_bedrock</code>. | *** {{MC/Nbt|string|name}}: Data name, either <code>product_minecraft</code>, <code>game_minecraft</code>, <code>product_minecraft_bedrock</code> or <code>game_minecraft_bedrock</code>. | ||
** {{Nbt|string|signature}}: JWT signature. | ** {{MC/Nbt|string|signature}}: JWT signature. | ||
** {{Nbt|string|keyID}}: Unknown. | ** {{MC/Nbt|string|keyID}}: Unknown. | ||
</div> | </div> | ||
| Line 403: | Line 403: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|id}}: Player's UUID. | ** {{MC/Nbt|string|id}}: Player's UUID. | ||
** {{Nbt|string|name}}: Player name. | ** {{MC/Nbt|string|name}}: Player name. | ||
** {{Nbt|list|skins}}: A list of info of all the skins the player owns. | ** {{MC/Nbt|list|skins}}: A list of info of all the skins the player owns. | ||
*** {{Nbt|compound}}: A skin. | *** {{MC/Nbt|compound}}: A skin. | ||
**** {{Nbt|string|id}}: Skin's UUID. | **** {{MC/Nbt|string|id}}: Skin's UUID. | ||
**** {{Nbt|string|state}}: Usage status for the skin. <code>ACTIVE</code> when the skin is the player's current skin, and <code>INACTIVE</code> when the skin was previously used. | **** {{MC/Nbt|string|state}}: Usage status for the skin. <code>ACTIVE</code> when the skin is the player's current skin, and <code>INACTIVE</code> when the skin was previously used. | ||
**** {{Nbt|string|url}}: URL to the skin. | **** {{MC/Nbt|string|url}}: URL to the skin. | ||
**** {{Nbt|string|variant}}: Skin variant. <code>CLASSIC</code> for the Steve model and <code>SLIM</code> for the Alex model. | **** {{MC/Nbt|string|variant}}: Skin variant. <code>CLASSIC</code> for the Steve model and <code>SLIM</code> for the Alex model. | ||
** {{Nbt|list|capes}}: A list of info of all the capes the player owns. | ** {{MC/Nbt|list|capes}}: A list of info of all the capes the player owns. | ||
*** {{Nbt|compound}}: A cape. | *** {{MC/Nbt|compound}}: A cape. | ||
**** {{Nbt|string|id}}: Cape's UUID. | **** {{MC/Nbt|string|id}}: Cape's UUID. | ||
**** {{Nbt|string|state}}: Usage status for the cape. <code>ACTIVE</code> when the cape is the player's current cape, and <code>INACTIVE</code> when the cape is owned but not displayed in-game. | **** {{MC/Nbt|string|state}}: Usage status for the cape. <code>ACTIVE</code> when the cape is the player's current cape, and <code>INACTIVE</code> when the cape is owned but not displayed in-game. | ||
**** {{Nbt|string|url}}: URL to the cape. | **** {{MC/Nbt|string|url}}: URL to the cape. | ||
**** {{Nbt|string|alias}}: Alias for the cape. | **** {{MC/Nbt|string|alias}}: Alias for the cape. | ||
</div> | </div> | ||
| Line 427: | Line 427: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|compound|privileges}}: Player's privileges | ** {{MC/Nbt|compound|privileges}}: Player's privileges | ||
*** {{Nbt|compound|onlineChat}}: Privilege of accepting chat messages | *** {{MC/Nbt|compound|onlineChat}}: Privilege of accepting chat messages | ||
**** {{Nbt|boolean|enable}} | **** {{MC/Nbt|boolean|enable}} | ||
*** {{Nbt|compound|multiplayerServer}}: Privilege of joining servers. | *** {{MC/Nbt|compound|multiplayerServer}}: Privilege of joining servers. | ||
**** {{Nbt|boolean|enable}} | **** {{MC/Nbt|boolean|enable}} | ||
*** {{Nbt|compound|multiplayerRealms}}: Privilege of joining Realms. | *** {{MC/Nbt|compound|multiplayerRealms}}: Privilege of joining Realms. | ||
**** {{Nbt|boolean|enable}} | **** {{MC/Nbt|boolean|enable}} | ||
*** {{Nbt|compound|telemetry}}: Privilege of sending telemetry. | *** {{MC/Nbt|compound|telemetry}}: Privilege of sending telemetry. | ||
**** {{Nbt|boolean|enable}} | **** {{MC/Nbt|boolean|enable}} | ||
*** {{Nbt|compound|optionalTelemetry}}: Privilege of sending optional telemetry. | *** {{MC/Nbt|compound|optionalTelemetry}}: Privilege of sending optional telemetry. | ||
**** {{Nbt|boolean|enable}} | **** {{MC/Nbt|boolean|enable}} | ||
** {{Nbt|compound|profanityFilterPreferences}}: Profanity filter settings. | ** {{MC/Nbt|compound|profanityFilterPreferences}}: Profanity filter settings. | ||
*** {{Nbt|boolean|profanityFilterOn}}: If Realms profanity filter is on. | *** {{MC/Nbt|boolean|profanityFilterOn}}: If Realms profanity filter is on. | ||
** {{Nbt|compound|banStatus}}: Player's ban status | ** {{MC/Nbt|compound|banStatus}}: Player's ban status | ||
*** {{Nbt|compound|bannedScopes}}: Scope in which the player is banned. | *** {{MC/Nbt|compound|bannedScopes}}: Scope in which the player is banned. | ||
**** {{Nbt|compound}}: Ban scope. If the player is not banned, these objects do not exist. Only <code>MULTIPLAYER</code> exists. | **** {{MC/Nbt|compound}}: Ban scope. If the player is not banned, these objects do not exist. Only <code>MULTIPLAYER</code> exists. | ||
***** {{Nbt|string|banId}}: UUID of the ban. | ***** {{MC/Nbt|string|banId}}: UUID of the ban. | ||
***** {{Nbt|string|expires}}: When the ban expires. This does not exist if the player is permanently banned. | ***** {{MC/Nbt|string|expires}}: When the ban expires. This does not exist if the player is permanently banned. | ||
***** {{Nbt|string|reason}}: Reason for the ban. | ***** {{MC/Nbt|string|reason}}: Reason for the ban. | ||
***** {{Nbt|string|reasonMessage}}: Ban message displayed. | ***** {{MC/Nbt|string|reasonMessage}}: Ban message displayed. | ||
</div> | </div> | ||
| Line 454: | Line 454: | ||
; Payload | ; Payload | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|compound|profanityFilterPreferences}}: Realms profanity filter options. | ** {{MC/Nbt|compound|profanityFilterPreferences}}: Realms profanity filter options. | ||
*** {{Nbt|boolean|profanityFilterOn}}: If filter is on. | *** {{MC/Nbt|boolean|profanityFilterOn}}: If filter is on. | ||
</div> | </div> | ||
| Line 472: | Line 472: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|list|blockedProfiles}}: A list of blocked players whose chat messages and Realms invitations are ignored. | ** {{MC/Nbt|list|blockedProfiles}}: A list of blocked players whose chat messages and Realms invitations are ignored. | ||
*** {{Nbt|string}}: UUID for the blocked player. | *** {{MC/Nbt|string}}: UUID for the blocked player. | ||
</div> | </div> | ||
| Line 484: | Line 484: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|compound|keyPair}}: Keypair used for signature. | ** {{MC/Nbt|compound|keyPair}}: Keypair used for signature. | ||
*** {{Nbt|string|privateKey}}: Private key. Starts with {{ | *** {{MC/Nbt|string|privateKey}}: Private key. Starts with {{MC/Cd|-----BEGIN RSA PRIVATE KEY-----}} and ends with {{MC/Cd|-----END RSA PRIVATE KEY-----}}. | ||
*** {{Nbt|string|publicKey}}: Public key. Starts with{{ | *** {{MC/Nbt|string|publicKey}}: Public key. Starts with{{MC/Cd|-----BEGIN RSA PUBLIC KEY-----}} and ends with {{MC/Cd|-----END RSA PUBLIC KEY-----}}. | ||
** {{Nbt|string|publicKeySignature}}: Deprecated, see below. | ** {{MC/Nbt|string|publicKeySignature}}: Deprecated, see below. | ||
** {{Nbt|string|publicKeySignatureV2}}: Public key signature. | ** {{MC/Nbt|string|publicKeySignatureV2}}: Public key signature. | ||
** {{Nbt|string|expiresAt}}: When the keypair expires. | ** {{MC/Nbt|string|expiresAt}}: When the keypair expires. | ||
** {{Nbt|string|refreshedAfter}}: When the keypair should be refreshed. | ** {{MC/Nbt|string|refreshedAfter}}: When the keypair should be refreshed. | ||
</div> | </div> | ||
| Line 501: | Line 501: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|changedAt}}: The last time the name has been changed. | ** {{MC/Nbt|string|changedAt}}: The last time the name has been changed. | ||
** {{Nbt|string|createdAt}}: The time the player profile is created. | ** {{MC/Nbt|string|createdAt}}: The time the player profile is created. | ||
** {{Nbt|boolean|nameChangeAllowed}}: If the player can change name. | ** {{MC/Nbt|boolean|nameChangeAllowed}}: If the player can change name. | ||
</div> | </div> | ||
| Line 523: | Line 523: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|status}}: Status of the name. <code>DUPLICATE</code> means the name is taken. <code>AVAILABLE</code> means the name is available.<code>NOT_ALLOWED</code> means the name does not meet requirements. | ** {{MC/Nbt|string|status}}: Status of the name. <code>DUPLICATE</code> means the name is taken. <code>AVAILABLE</code> means the name is available.<code>NOT_ALLOWED</code> means the name does not meet requirements. | ||
</div> | </div> | ||
| Line 537: | Line 537: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|id}}: Player's UUID. | ** {{MC/Nbt|string|id}}: Player's UUID. | ||
** {{Nbt|string|name}}: Player name. | ** {{MC/Nbt|string|name}}: Player name. | ||
** {{Nbt|list|skins}}: A list of info of all the skins the player owns. | ** {{MC/Nbt|list|skins}}: A list of info of all the skins the player owns. | ||
*** {{Nbt|compound}}: A skin. | *** {{MC/Nbt|compound}}: A skin. | ||
**** {{Nbt|string|id}}: Cape's UUID. | **** {{MC/Nbt|string|id}}: Cape's UUID. | ||
**** {{Nbt|string|state}}: Usage status for the cape. | **** {{MC/Nbt|string|state}}: Usage status for the cape. | ||
**** {{Nbt|string|url}}: URL to the skin. | **** {{MC/Nbt|string|url}}: URL to the skin. | ||
**** {{Nbt|string|variant}}: Skin variant. <code>CLASSIC</code> for the Steve model and <code>SLIM</code> for the Alex model. | **** {{MC/Nbt|string|variant}}: Skin variant. <code>CLASSIC</code> for the Steve model and <code>SLIM</code> for the Alex model. | ||
** {{Nbt|list|capes}}: A list of info of all the capes the player owns. | ** {{MC/Nbt|list|capes}}: A list of info of all the capes the player owns. | ||
*** {{Nbt|compound}}: A cape. | *** {{MC/Nbt|compound}}: A cape. | ||
**** {{Nbt|string|id}}: Cape's UUID. | **** {{MC/Nbt|string|id}}: Cape's UUID. | ||
**** {{Nbt|string|state}}: Usage status for the cape. | **** {{MC/Nbt|string|state}}: Usage status for the cape. | ||
**** {{Nbt|string|url}}: URL to the cape. | **** {{MC/Nbt|string|url}}: URL to the cape. | ||
**** {{Nbt|string|alias}}: Alias for the cape. | **** {{MC/Nbt|string|alias}}: Alias for the cape. | ||
</div> | </div> | ||
| Line 557: | Line 557: | ||
{| class="wikitable mw-collapsible mw-collapsed" | {| class="wikitable mw-collapsible mw-collapsed" | ||
! HTTP status code | ! HTTP status code | ||
! {{ | ! {{MC/Cd|error}} | ||
! {{ | ! {{MC/Cd|errorMessage}} | ||
! Explanation | ! Explanation | ||
|- | |- | ||
| Line 581: | Line 581: | ||
; Payload | ; Payload | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|variant}}: Skin variant. <code>classic</code> for the Steve model and <code>slim</code> for the Alex model. | ** {{MC/Nbt|string|variant}}: Skin variant. <code>classic</code> for the Steve model and <code>slim</code> for the Alex model. | ||
** {{Nbt|string|url}}: URL to the skin. | ** {{MC/Nbt|string|url}}: URL to the skin. | ||
</div> | </div> | ||
| Line 597: | Line 597: | ||
Payload is made up of two parts: | Payload is made up of two parts: | ||
* {{ | * {{MC/Cd|variant}}: Skin variant. <code>classic</code> for the Steve model and <code>slim</code> for the Alex model. | ||
* {{ | * {{MC/Cd|file}}: Image data for the new skin. See example below. | ||
; Request (POST) | ; Request (POST) | ||
| Line 634: | Line 634: | ||
; Payload | ; Payload | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|capeId}}: UUID for the cape to activate | ** {{MC/Nbt|string|capeId}}: UUID for the cape to activate | ||
</div> | </div> | ||
| Line 647: | Line 647: | ||
{| class="wikitable mw-collapsible mw-collapsed" | {| class="wikitable mw-collapsible mw-collapsed" | ||
! HTTP status code | ! HTTP status code | ||
! {{ | ! {{MC/Cd|error}} | ||
! {{ | ! {{MC/Cd|errorMessage}} | ||
! Explanation | ! Explanation | ||
|- | |- | ||
| Line 674: | Line 674: | ||
; Payload | ; Payload | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|string|accessToken}}: Minecraft access token. | ** {{MC/Nbt|string|accessToken}}: Minecraft access token. | ||
** {{Nbt|string|selectedProfile}}: Player UUID without dashes. | ** {{MC/Nbt|string|selectedProfile}}: Player UUID without dashes. | ||
** {{Nbt|string|serverId}}: Server ID. See below. | ** {{MC/Nbt|string|serverId}}: Server ID. See below. | ||
</div> | </div> | ||
| Line 721: | Line 721: | ||
; Response | ; Response | ||
<div class="treeview"> | <div class="treeview"> | ||
* {{Nbt|compound}} Root tag | * {{MC/Nbt|compound}} Root tag | ||
** {{Nbt|list|profilePropertyKeys}}: A list of public keys used for verifying player properties (such as skin and cape textures), from e.g. <code><nowiki>https://sessionserver.mojang.com/session/minecraft/profile/</nowiki><''UUID''>?unsigned=false</code>. A player property is considered valid by the client iff signed by any of these keys. | ** {{MC/Nbt|list|profilePropertyKeys}}: A list of public keys used for verifying player properties (such as skin and cape textures), from e.g. <code><nowiki>https://sessionserver.mojang.com/session/minecraft/profile/</nowiki><''UUID''>?unsigned=false</code>. A player property is considered valid by the client iff signed by any of these keys. | ||
*** {{Nbt|string}}: Base64-encoded DER public key. | *** {{MC/Nbt|string}}: Base64-encoded DER public key. | ||
** {{Nbt|list|playerCertificateKeys}}: A list of public keys used for verifying player public keys, e.g. from <code><nowiki>https://api.minecraftservices.com/player/certificates</nowiki></code>. A player certificate is considered valid by the client iff signed by any of these keys. | ** {{MC/Nbt|list|playerCertificateKeys}}: A list of public keys used for verifying player public keys, e.g. from <code><nowiki>https://api.minecraftservices.com/player/certificates</nowiki></code>. A player certificate is considered valid by the client iff signed by any of these keys. | ||
*** {{Nbt|string}}: Base64-encoded DER public key. | *** {{MC/Nbt|string}}: Base64-encoded DER public key. | ||
</div> | </div> | ||
== History == | == History == | ||
{{HistoryTable | {{HistoryTable | ||
|{{HistoryLine||April 14, 2014|link=https://github.com/Mojang/AccountsClient|Mojang API is released.}} | |{{MC/HistoryLine||April 14, 2014|link=https://github.com/Mojang/AccountsClient|Mojang API is released.}} | ||
|{{HistoryLine||November 2020|link=https://bugs.mojang.com/browse/WEB-3367|Endpoint for obtaining player UUID no longer supports the {{ | |{{HistoryLine||November 2020|link=https://bugs.mojang.com/browse/WEB-3367|Endpoint for obtaining player UUID no longer supports the {{MC/Cd|at}} parameter.}} | ||
|{{HistoryLine||October 8, 2021|link=https://bugs.mojang.com/browse/WEB-2303?focusedCommentId=1086543&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-1086543|Endpoint for querying Mojang API status is removed. The endpoint was <code><nowiki>https://status.mojang.com/check</nowiki></code>.}} | |{{MC/HistoryLine||October 8, 2021|link=https://bugs.mojang.com/browse/WEB-2303?focusedCommentId=1086543&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-1086543|Endpoint for querying Mojang API status is removed. The endpoint was <code><nowiki>https://status.mojang.com/check</nowiki></code>.}} | ||
|{{HistoryLine||May 8, 2022|link={{tweet|Mojang_Ined|1501541417784852484}}|Endpoint for querying Minecraft sales is removed. The endpoint was <code><nowiki>https://api.mojang.com/orders/statistics</nowiki></code>.}} | |{{HistoryLine||May 8, 2022|link={{tweet|Mojang_Ined|1501541417784852484}}|Endpoint for querying Minecraft sales is removed. The endpoint was <code><nowiki>https://api.mojang.com/orders/statistics</nowiki></code>.}} | ||
|{{HistoryLine||September 13, 2022|link=https://help.minecraft.net/hc/en-us/articles/8969841895693-Username-History-API-Removal-FAQ-|The endpoint for querying names a player used to use is removed. The endpoint was <code><nowiki>https://api.mojang.com/user/profiles/</nowiki><''UUID''>/names</code>.}} | |{{MC/HistoryLine||September 13, 2022|link=https://help.minecraft.net/hc/en-us/articles/8969841895693-Username-History-API-Removal-FAQ-|The endpoint for querying names a player used to use is removed. The endpoint was <code><nowiki>https://api.mojang.com/user/profiles/</nowiki><''UUID''>/names</code>.}} | ||
|{{HistoryLine||January 15, 2025|link=https://bugs.mojang.com/browse/WEB-7591?focusedId=1375404&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-1375404|The endpoint for querying UUIDs based on a player's name has experimental rate limits introduced. The endpoint is <code><nowiki>https://api.mojang.com/users/profiles/minecraft/</nowiki><''username''>/names</code>.}} | |{{MC/HistoryLine||January 15, 2025|link=https://bugs.mojang.com/browse/WEB-7591?focusedId=1375404&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-1375404|The endpoint for querying UUIDs based on a player's name has experimental rate limits introduced. The endpoint is <code><nowiki>https://api.mojang.com/users/profiles/minecraft/</nowiki><''username''>/names</code>.}} | ||
}} | }} | ||
| Line 763: | Line 763: | ||
== References == | == References == | ||
{{ | {{MC/Reflist}} | ||
== Navigation == | == Navigation == | ||
{{Navbox Java Edition technical|General}} | {{MC/Navbox Java Edition technical|General}} | ||
[[Category:Java Edition protocol]] | [[Category:Java Edition protocol]] | ||
{{ | {{MC/License wiki.vg}} | ||
de:Mojang API | |||
lzh:魔贊卯口 | |||
zh:Mojang API | |||
Latest revision as of 20:39, 9 April 2026
This page provides documentation for API endpoints provided by Mojang Studios which allows user to query player data and make changes programmatically.
Most of the API has a per-IP ratelimit of 200 requests per 2 minutes. For IPv6, the ratelimits are bucketed by /56 subnet. Some endpoints have different ratelimits.
Request and response
For requests with a payload, the following restrictions apply:
- Request must include the
Content-Typeheader, which must be application/json. Otherwise, the server returns HTTP 415. - Payload must be a valid json. Otherwise, the server returns HTTP 400.
If the request is successful, the server:
- Returns a successful response code (HTTP 2XX)
- Returns an empty payload (with HTTP 204) or a valid json
Otherwise, if the request fails, the server returns a non-2XX HTTP status code with this payload:
- Template:Nbt/sprite: Root tag.
- Template:Nbt/sprite error: Error identifier
- Template:Nbt/sprite errorMessage: Description of the error
- Template:Nbt/sprite cause: Description of the cause of the error
These are some common causes:
| HTTP status code |
|
|
Explanation |
|---|---|---|---|
| 400 | IllegalArgumentException | Depends on the endpoint | Incorrect or invalid argument in the request. |
| MismatchedInputException | JSON payload does not meet the required schema or payload is not an invalid JSON. | ||
| JsonParseException | |||
| 401 | (empty payload) | (empty payload) | Endpoint requires authentication, but request header does not have an Authorization header or the token is invalid.
|
| Unauthorized | The request requires user authentication | Endpoint requires authentication, but request header does not have an Authorization header.
| |
| 403 | ForbiddenOperationException | Forbidden | Invalid auth token. |
|
Your account has been suspended. Please contact customer service. | Account has been banned/suspended state by triggering a high volume of erroneous requests. See #Account suspensions. | |
| 404 | Not Found | The server has not found anything matching the request URI | Endpoint does not exist. |
| 405 | Method Not Allowed | The method specified in the request is not allowed for the resource identified by the request URI | Request method is not supported. |
| 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 |
Template:Redr request header does not match the type the endpoint allows. |
Account suspensions
A Minecraft account can be entered into a banned/suspended state by triggering a high volume of erroneous requests, such as a high volume of 429s while uploading a skin.
These suspensions appear to be temporary, although this is speculation and the exact functionality of this automatic suspension system is unknown.
POST https://api.minecraftservices.com/authentication/login_with_xbox
Returns 403 with the following JSON data <syntaxhighlight lang="json"> { "path": "/authentication/login_with_xbox", "details": { "reason": "ACCOUNT_SUSPENDED" }, "errorMessage": "Your account has been suspended. Please contact customer service." } </syntaxhighlight>
Other services will report that the account is banned, such as servers serving the otherwise unused message You are banned from playing online.
These suspensions typically clear within 24 hours but may require contacting Minecraft support if they don't.
Query player information
These endpoints do not need an access token, and some endpoints can query registered account that do not own the game.
Query player's username
- Input
Player's name (case insensitive).
- Request (GET)
https://api.mojang.com/users/profiles/minecraft/<player name>- This will occasionally return random 403 errors due to a misconfiguration<ref>https://bugs.mojang.com/browse/WEB-7591?focusedId=1375404&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-1375404</ref> by Mojang.
https://api.minecraftservices.com/minecraft/profile/lookup/name/<player name>https://api.mojang.com/minecraft/profile/lookup/name/<player name>
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite id: Minecraft:UUID of the player.
- Template:Nbt/sprite name: Name of the player, case sensitive.
- Template:Nbt/sprite legacy: Included in response if the account has not migrated to Mojang account.
- Template:Nbt/sprite demo: Included in response if the account does not own the game.
- Example
https://api.mojang.com/users/profiles/minecraft/jeb_
Player jeb_'s UUID.
<syntaxhighlight lang="json"> {
"name": "jeb_", "id": "853c80ef3c3749fdaa49938b674adae6"
} </syntaxhighlight>
- Error
- HTTP 404 is returned if no player with such name exists.
Query player's UUID
- Input
Player's UUID.
- Request (GET)
https://api.minecraftservices.com/minecraft/profile/lookup/<UUID>
- Response
The same as #Query player's username.
Query player UUIDs in batch
- Payload
A JSON array with no more than 10 player names (case insensitive).
- Request (POST)
https://api.mojang.com/profiles/minecrafthttps://api.minecraftservices.com/minecraft/profile/lookup/bulk/bynamehttps://api.mojang.com/minecraft/profile/lookup/bulk/byname
- Response
- Template:Nbt/sprite The UUID list for all the players. For players that does not exist, no result is returned.
- Template:Nbt/sprite Player name.
- Template:Nbt/sprite id: Minecraft:UUID of the player.
- Template:Nbt/sprite name: Name of the player, case sensitive.
- Template:Nbt/sprite legacy: Included in response if the account has not migrated to Mojang account.
- Template:Nbt/sprite demo: Included in response if the account does not own the game.
- Template:Nbt/sprite Player name.
- Example
Request with payload ["jeb_","notch"].
<syntaxhighlight lang="json">
[
{
"id": "853c80ef3c3749fdaa49938b674adae6",
"name": "jeb_"
},
{
"id": "069a79f444e94726a5befca90e38aaf5",
"name": "Notch"
}
] </syntaxhighlight>
| HTTP status code |
|
|
Explanation |
|---|---|---|---|
| 400 | CONSTRAINT_VIOLATION | size must be between 1 and 10 | RequestPayload is an empty array. |
| RequestPayload is has more than 10 elements. | |||
| Invalid profile name | RequestPayload includes an empty string. |
Query player's skin and cape
- Input
Player UUID and whether the request is signed.
- Request (GET)
https://sessionserver.mojang.com/session/minecraft/profile/<UUID>- Ratelimited at about 400 requests per 10 seconds.
https://sessionserver.mojang.com/session/minecraft/profile/<UUID>?unsigned=false
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite id: Player's Minecraft:UUID.
- Template:Nbt/sprite name: Player name, case sensitive.
- Template:Nbt/sprite legacy: Included in response if the account has not migrated to Mojang account.
- Template:Nbt/sprite properties: A list of player properties.
- Template:Nbt/sprite name: Name of the property. For now, the only property that exists is
textures. - Template:Nbt/sprite signature: Signature signed with Yggdrasil private key as Base64 string, only exists when
unsigned=false. - Template:Nbt/sprite value: Base64 string with all player textures (skin and cape). The decoded string includes:
- Template:Nbt/sprite Texture object.
- Template:Nbt/sprite timestamp: Unix time in milliseconds the texture is accessed.
- Template:Nbt/sprite profileId: Player's UUID without dashes.
- Template:Nbt/sprite profileName: Player name.
- Template:Nbt/sprite signatureRequired: Only exists when
unsigned=false. - Template:Nbt/sprite textures: Texture.
- Template:Nbt/sprite SKIN: Skin texture. This does not exist if the player does not have a custom skin.
- Template:Nbt/sprite url: URL to the skin texture.
- Template:Nbt/sprite metadata: Optional. Metadata for the skin.
- Template:Nbt/sprite model:
slim. Only exists when skin model is Alex. When skin model is Steve, this metadata does not exist.
- Template:Nbt/sprite model:
- Template:Nbt/sprite CAPE: Cape texture. If the player does not have a cape, this does not exist.
- Template:Nbt/sprite url: URL to the cape texture.
- Template:Nbt/sprite SKIN: Skin texture. This does not exist if the player does not have a custom skin.
- Template:Nbt/sprite Texture object.
- Template:Nbt/sprite name: Name of the property. For now, the only property that exists is
- Example
https://sessionserver.mojang.com/session/minecraft/profile/853c80ef3c3749fdaa49938b674adae6
Returns:
<syntaxhighlight lang="json">
{
"id": "853c80ef3c3749fdaa49938b674adae6",
"name": "jeb_",
"properties": [
{
"name": "textures",
"value": "ewogICJ0aW1lc3R..."
}
]
} </syntaxhighlight> Content in Template:Nbt/sprite value after Base64 decoded: <syntaxhighlight lang="json"> {
"timestamp": 1653838459263,
"profileId": "853c80ef3c3749fdaa49938b674adae6",
"profileName": "jeb_",
"textures": {
"SKIN": {
"url": "http://textures.minecraft.net/texture/7fd9ba42a7c81eeea22f1524271ae85a8e045ce0af5a6ae16c6406ae917e68b5"
},
"CAPE": {
"url": "http://textures.minecraft.net/texture/9e507afc56359978a3eb3e32367042b853cddd0995d17d0da995662913fb00f7"
}
}
} </syntaxhighlight>
- Error
| HTTP status code |
|
|
Explanation |
|---|---|---|---|
| 204 | (empty payload) | (empty payload) | This UUID does not have an associated player |
| 400 | (empty) | Not a valid UUID: <inputted argument> | UUID is invalid. |
Microsoft authentication
Authentication for Microsoft accounts. Before using Microsoft auth, an Microsoft Azure Application must be created to obtain OAuth 2.0 client ID and token, which can then be used to obtain a Microsoft token. When obtaining the token, the
- REDIRECT Template:Code
Template:Redr parameter should include Template:Samp to obtain an Xbox Live token.
Obtain an Xbox Live token with Microsoft token
- Payload
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite Properties: Authentication properties
- Template:Nbt/sprite AuthMethod: Login method. This should be
RPS. - Template:Nbt/sprite SiteName: Website name. This should be
user.auth.xboxlive.com. - Template:Nbt/sprite RpsTicket: Ticket used for logging in. Value should be
d=<Microsoft access token>.
- Template:Nbt/sprite AuthMethod: Login method. This should be
- Template:Nbt/sprite RelyingParty: Replying party. This should be
http://auth.xboxlive.com. - Template:Nbt/sprite TokenType: Type of the access token. This should be
JWT.
- Template:Nbt/sprite Properties: Authentication properties
- Request (POST)
https://user.auth.xboxlive.com/user/authenticate
SSL renegotiation required in SSL implementation.
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite IssueInstant: Time when obtaining the Xbox Live token.
- Template:Nbt/sprite NotAfter: Time the Xbox Live token is expired.
- Template:Nbt/sprite Token: Xbox Live access token.
- Template:Nbt/sprite DisplayClaims: Unknown.
- Template:Nbt/sprite xui: Unknown.
- Template:Nbt/sprite
- Template:Nbt/sprite uhs: User hashcode.
- Template:Nbt/sprite
- Template:Nbt/sprite xui: Unknown.
Obtain an XSTS token with Xbox Live token
- Payload
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite Properties: Auth properties.
- Template:Nbt/sprite SandboxId: Sandbox ID. This should be
RETAIL. - Template:Nbt/sprite UserTokens: User's Xbox Live token.
- Template:Nbt/sprite: User's Xbox Live token obtained in the previous step.
- Template:Nbt/sprite SandboxId: Sandbox ID. This should be
- Template:Nbt/sprite RelyingParty: Replying party. This should be
rp://api.minecraftservices.com/. - Template:Nbt/sprite TokenType: Type of the access token. This should be
JWT.
- Template:Nbt/sprite Properties: Auth properties.
- Request (POST)
https://xsts.auth.xboxlive.com/xsts/authorize
SSL renegotiation required in SSL implementation.
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite IssueInstant: Time when obtaining the XSTS token.
- Template:Nbt/sprite NotAfter: Time the XSTS token is expired.
- Template:Nbt/sprite Token: XSTS access token.
- Template:Nbt/sprite DisplayClaims: Unknown.
- Template:Nbt/sprite xui: Unknown.
- Template:Nbt/sprite
- Template:Nbt/sprite uhs: User hashcode.
- Template:Nbt/sprite
- Template:Nbt/sprite xui: Unknown.
- Error
HTTP 401 is returned if an error occurs in obtaining the XSTS token.
Obtain Minecraft access token with XSTS token
- Payload
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite identityToken: Identity token. The value should be
XBL3.0 x=<User hashcode>;<XSTS access token>.
- Template:Nbt/sprite identityToken: Identity token. The value should be
- Request (POST)
https://api.minecraftservices.com/authentication/login_with_xbox
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite username: UUID (not the UUID for the player)
- Template:Nbt/sprite roles: Unknown, empty.
- Template:Nbt/sprite access_token: Minecraft access token.
- Template:Nbt/sprite token_type: Token type. This is always
Bearer. - Template:Nbt/sprite expires_in: Time period until the token expires in seconds.
Check if the account owns Minecraft
- Request header
Authorization should be Bearer <Minecraft access token>.
- Request (GET)
https://api.minecraftservices.com/entitlements/license?requestId=<v4 UUID>
- Response
If the account owns Minecraft, returns:
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite items: Products licensed to use.
- Template:Nbt/sprite name: Data name, either
product_minecraft,game_minecraft,product_minecraft_bedrockorgame_minecraft_bedrock.
- Template:Nbt/sprite name: Data name, either
- Template:Nbt/sprite signature: JWT signature.
- Template:Nbt/sprite keyID: Unknown.
- Template:Nbt/sprite items: Products licensed to use.
If the account does not own Minecraft or is playing with Xbox Game Pass, empty payload is returned.
Player config
These endpoints are at https://api.minecraftservices.com, and all requires the Authorization header in request with value Bearer <Minecraft access token>. HTTP 401 is returned if token is missing or invalid.
Query player profile
- Request (GET)
/minecraft/profile
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite id: Player's UUID.
- Template:Nbt/sprite name: Player name.
- Template:Nbt/sprite skins: A list of info of all the skins the player owns.
- Template:Nbt/sprite: A skin.
- Template:Nbt/sprite id: Skin's UUID.
- Template:Nbt/sprite state: Usage status for the skin.
ACTIVEwhen the skin is the player's current skin, andINACTIVEwhen the skin was previously used. - Template:Nbt/sprite url: URL to the skin.
- Template:Nbt/sprite variant: Skin variant.
CLASSICfor the Steve model andSLIMfor the Alex model.
- Template:Nbt/sprite: A skin.
- Template:Nbt/sprite capes: A list of info of all the capes the player owns.
- Template:Nbt/sprite: A cape.
- Template:Nbt/sprite id: Cape's UUID.
- Template:Nbt/sprite state: Usage status for the cape.
ACTIVEwhen the cape is the player's current cape, andINACTIVEwhen the cape is owned but not displayed in-game. - Template:Nbt/sprite url: URL to the cape.
- Template:Nbt/sprite alias: Alias for the cape.
- Template:Nbt/sprite: A cape.
Query player attributes
- Request (GET)
/player/attributes
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite privileges: Player's privileges
- Template:Nbt/sprite onlineChat: Privilege of accepting chat messages
- Template:Nbt/sprite enable
- Template:Nbt/sprite multiplayerServer: Privilege of joining servers.
- Template:Nbt/sprite enable
- Template:Nbt/sprite multiplayerRealms: Privilege of joining Realms.
- Template:Nbt/sprite enable
- Template:Nbt/sprite telemetry: Privilege of sending telemetry.
- Template:Nbt/sprite enable
- Template:Nbt/sprite optionalTelemetry: Privilege of sending optional telemetry.
- Template:Nbt/sprite enable
- Template:Nbt/sprite onlineChat: Privilege of accepting chat messages
- Template:Nbt/sprite profanityFilterPreferences: Profanity filter settings.
- Template:Nbt/sprite profanityFilterOn: If Realms profanity filter is on.
- Template:Nbt/sprite banStatus: Player's ban status
- Template:Nbt/sprite bannedScopes: Scope in which the player is banned.
- Template:Nbt/sprite: Ban scope. If the player is not banned, these objects do not exist. Only
MULTIPLAYERexists.- Template:Nbt/sprite banId: UUID of the ban.
- Template:Nbt/sprite expires: When the ban expires. This does not exist if the player is permanently banned.
- Template:Nbt/sprite reason: Reason for the ban.
- Template:Nbt/sprite reasonMessage: Ban message displayed.
- Template:Nbt/sprite: Ban scope. If the player is not banned, these objects do not exist. Only
- Template:Nbt/sprite bannedScopes: Scope in which the player is banned.
- Template:Nbt/sprite privileges: Player's privileges
Modify player attributes
- Payload
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite profanityFilterPreferences: Realms profanity filter options.
- Template:Nbt/sprite profanityFilterOn: If filter is on.
- Template:Nbt/sprite profanityFilterPreferences: Realms profanity filter options.
- Request (POST)
/player/attributes
- Response
The same as #Query player attributes.
Get list of blocked users
- Request (GET)
/privacy/blocklist
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite blockedProfiles: A list of blocked players whose chat messages and Realms invitations are ignored.
- Template:Nbt/sprite: UUID for the blocked player.
- Template:Nbt/sprite blockedProfiles: A list of blocked players whose chat messages and Realms invitations are ignored.
Get keypair for signature
- Request (POST)
/player/certificates
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite keyPair: Keypair used for signature.
- Template:Nbt/sprite privateKey: Private key. Starts with
- Template:Nbt/sprite keyPair: Keypair used for signature.
- REDIRECT Template:Code
Template:Redr and ends with
- REDIRECT Template:Code
- Template:Nbt/sprite publicKey: Public key. Starts with
- REDIRECT Template:Code
Template:Redr and ends with
- REDIRECT Template:Code
- Template:Nbt/sprite publicKeySignature: Deprecated, see below.
- Template:Nbt/sprite publicKeySignatureV2: Public key signature.
- Template:Nbt/sprite expiresAt: When the keypair expires.
- Template:Nbt/sprite refreshedAfter: When the keypair should be refreshed.
Query player's name change information
- Request (GET)
/minecraft/profile/namechange
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite changedAt: The last time the name has been changed.
- Template:Nbt/sprite createdAt: The time the player profile is created.
- Template:Nbt/sprite nameChangeAllowed: If the player can change name.
Check gift code validity
- Request (GET)
/productvoucher/giftcode
- Response
Returns HTTP 200 or 204 if the gift code is valid. Otherwise returns HTTP 404.
Check name availability
- Request (GET)
/minecraft/profile/name/<name to be checked>/available
- This endpoint has a per-account ratelimit of 20 requests per 5 minutes.
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite status: Status of the name.
DUPLICATEmeans the name is taken.AVAILABLEmeans the name is available.NOT_ALLOWEDmeans the name does not meet requirements.
- Template:Nbt/sprite status: Status of the name.
Change name
- Input
Name to change to
- Request (PUT)
/minecraft/profile/name/<name to change to>
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite id: Player's UUID.
- Template:Nbt/sprite name: Player name.
- Template:Nbt/sprite skins: A list of info of all the skins the player owns.
- Template:Nbt/sprite: A skin.
- Template:Nbt/sprite id: Cape's UUID.
- Template:Nbt/sprite state: Usage status for the cape.
- Template:Nbt/sprite url: URL to the skin.
- Template:Nbt/sprite variant: Skin variant.
CLASSICfor the Steve model andSLIMfor the Alex model.
- Template:Nbt/sprite: A skin.
- Template:Nbt/sprite capes: A list of info of all the capes the player owns.
- Template:Nbt/sprite: A cape.
- Template:Nbt/sprite id: Cape's UUID.
- Template:Nbt/sprite state: Usage status for the cape.
- Template:Nbt/sprite url: URL to the cape.
- Template:Nbt/sprite alias: Alias for the cape.
- Template:Nbt/sprite: A cape.
- Error
| HTTP status code |
|
|
Explanation |
|---|---|---|---|
| 400 | CONSTRAINT_VIOLATION | changeProfileName.profileName: Invalid profile name | Name does not meet requirement. The name must have less than or equal to 16 characters and must consist of alphanumericals and underscores. |
| 403 | (empty) | Could not change name for profile | Cannot change name. If detail.status is DUPLICATE, the name has already been taken.
|
| 429 | - | - | Too many rename requests sent. |
Change skin
- Payload
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite variant: Skin variant.
classicfor the Steve model andslimfor the Alex model. - Template:Nbt/sprite url: URL to the skin.
- Template:Nbt/sprite variant: Skin variant.
- Request (POST)
/minecraft/profile/skins
- Response
Returns the profile if operation succeeds.
Upload skin
- Payload
Payload is made up of two parts:
- REDIRECT Template:Code
Template:Redr: Skin variant. classic for the Steve model and slim for the Alex model.
- REDIRECT Template:Code
Template:Redr: Image data for the new skin. See example below.
- Request (POST)
/minecraft/profile/skins
- Example
<syntaxhighlight lang="bash"> 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 </syntaxhighlight>
- Response
Returns the profile if operation succeeds.
Reset skin
- Input
Player's UUID.
- Request (DELETE)
/minecraft/profile/skins/active
- Response
Returns the profile if operation succeeds.
Hide cape
- Request (DELETE)
/minecraft/profile/capes/active
- Response
Returns the profile if operation succeeds.
Show cape
- Payload
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite capeId: UUID for the cape to activate
- Request (PUT)
/minecraft/profile/capes/active
- Response
Returns the profile if operation succeeds.
- Error
| HTTP status code |
|
|
Explanation |
|---|---|---|---|
| 400 | (empty) | profile does not own cape | The player does not own the cape. |
Server
Query blocked server list
- Request (GET)
https://sessionserver.mojang.com/blockedservers
- Response
A text file where every line is the SHA-1 hash of a blocked server.
Verify login session on client
- Payload
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite accessToken: Minecraft access token.
- Template:Nbt/sprite selectedProfile: Player UUID without dashes.
- Template:Nbt/sprite serverId: Server ID. See below.
Server ID is obtained from the following algorithm:
<syntaxhighlight lang="java"> public static String generateServerId(String baseServerId, // Base server ID, usually an empty string""
PublicKey publicKey, // Server's RSA public key
SecretKey secretKey // The symmetric AES secret key used between server and client
) 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);
} </syntaxhighlight>
- Request (POST)
https://sessionserver.mojang.com/session/minecraft/join
- This endpoint has a per-account ratelimit of 6 joins per 30 seconds.
- Response
Returns HTTP 204 if authentication passes.
Verify login session on server
- Input
Case insensitive player name, server ID obtained by the above algorithm and the client IP (optional).
- Request (GET)
https://sessionserver.mojang.com/session/minecraft/hasJoined?username=<player name>&serverId=<Server ID>&ip=<Client IP>
- Response
Returns this payload if verification passes.
Get Mojang public keys
- Request (GET)
https://api.minecraftservices.com/publickeys
- Response
- Template:Nbt/sprite Root tag
- Template:Nbt/sprite profilePropertyKeys: A list of public keys used for verifying player properties (such as skin and cape textures), from e.g.
https://sessionserver.mojang.com/session/minecraft/profile/<UUID>?unsigned=false. A player property is considered valid by the client iff signed by any of these keys.- Template:Nbt/sprite: Base64-encoded DER public key.
- Template:Nbt/sprite playerCertificateKeys: A list of public keys used for verifying player public keys, e.g. from
https://api.minecraftservices.com/player/certificates. A player certificate is considered valid by the client iff signed by any of these keys.- Template:Nbt/sprite: Base64-encoded DER public key.
- Template:Nbt/sprite profilePropertyKeys: A list of public keys used for verifying player properties (such as skin and cape textures), from e.g.
History
References
This article is partially adapted from Mojang API on wiki.vg.
Examples
- C# - Full API wrapper
- C# - Full API wrapper with Mojang/Microsoft Authentication
- Dart - Almost full API wrapper with Mojang Authentication
- Go - Full API wrapper
- Go - UUIDs or names to profiles with skins, capes and name histories
- Python - Full API Wrapper. Also supports authentication & parts of the Minecraft website
- Python - Pymojang is a full wrapper around de Mojang API and Mojang Authentication API. Also support RCON, Query and Server List Ping
- Python - Full API wrapper (not updated since 2018)
- Python - UUIDs or names to profiles (not updated since 2018)
- PHP - Complete Mojang's API wrapper
- PHP - Almost full API wrapper with Mojang Authentication. Also support head rendering
- PHP - UUIDs or names to profiles with skins, heads and name histories
- PHP - UUIDs to names
- PHP - UUIDs to names, names to uuids
- Java - Almost full API Wrapper
- Java - Almost full API Wrapper with auth
- Java - Almost full API with Mojang Authentication and can also work as a console Application.
- JavaScript - UUIDs or names to profiles with skins, capes and name histories
- JavaScript/TypeScript - Almost full API wrapper
References
<references group="">
</references>
de:Mojang API lzh:魔贊卯口 zh:Mojang API