Mojang API

This page provides documentation for API endpoints provided by Mojang Studios which allows user to query player data and make changes programmatically.

Currently, the API is rate limited at 600 requests per 10 minutes.

Request and response

For requests with a payload, the following restrictions apply:

• Request must include the Content-Type header, 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:

• [NBT Compound / JSON Object]: Root tag.
  • [String] error: Error identifier
  • [String] errorMessage: Description of the error
  • [String] cause: Description of the cause of the error

These are some common causes:

HTTP status code	error	errorMessage	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.
	N/A	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	Content-Type 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

{
	"path": "/authentication/login_with_xbox",
	"details": {
		"reason": "ACCOUNT_SUSPENDED"
	},
	"errorMessage": "Your account has been suspended. Please contact customer service."
}

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 UUID

Input

Player's name (case insensitive).

Request (GET)

• https://api.mojang.com/users/profiles/minecraft/<player name>
  • This endpoint is currently very unreliable as of January 15, 2025 (frequent, random 403 errors) due to a misconfiguration by Mojang.
• https://api.minecraftservices.com/minecraft/profile/lookup/name/<player name>

Response

• [NBT Compound / JSON Object] Root tag
  • [String] id: UUID of the player.
  • [String] name: Name of the player, case sensitive.
  • [Boolean] legacy: Included in response if the account has not migrated to Mojang account.
  • [Boolean] 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.

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

Error

• HTTP 404 is returned if no player with such name exists.

Query player's username

Input

Player's username (case insensitive).

Request (GET)

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

Response

The same as #Query player's UUID.

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/minecraft
• https://api.minecraftservices.com/minecraft/profile/lookup/bulk/byname

Response

• [NBT List / JSON Array] The UUID list for all the players. For players that does not exist, no result is returned.
  • [NBT Compound / JSON Object] Player name.
    • [String] id: UUID of the player.
    • [String] name: Name of the player, case sensitive.
    • [Boolean] legacy: Included in response if the account has not migrated to Mojang account.
    • [Boolean] demo: Included in response if the account does not own the game.

Example

Request with payload ["jeb_","notch"].

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

HTTP status code	error	errorMessage	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>
• https://sessionserver.mojang.com/session/minecraft/profile/<UUID>?unsigned=false

Response

• [NBT Compound / JSON Object] Root tag
  • [String] id: Player's UUID.
  • [String] name: Player name, case sensitive.
  • [Boolean] legacy: Included in response if the account has not migrated to Mojang account.
  • [NBT List / JSON Array] properties: A list of player properties.
    • [String] name: Name of the property. For now, the only property that exists is textures.
    • [String] signature: Signature signed with Yggdrasil private key as Base64 string, only exists when unsigned=false.
    • [String] value: Base64 string with all player textures (skin and cape). The decoded string includes:
      • [NBT Compound / JSON Object] Texture object.
        • [Int] timestamp: Unix time in milliseconds the texture is accessed.
        • [String] profileId: Player's UUID without dashes.
        • [String] profileName: Player name.
        • [Boolean] signatureRequired: Only exists when unsigned=false.
        • [NBT Compound / JSON Object] textures: Texture.
          • [NBT Compound / JSON Object] SKIN: Skin texture. This does not exist if the player does not have a custom skin.
            • [String] url: URL to the skin texture.
            • [NBT Compound / JSON Object] metadata: Optional. Metadata for the skin.
              • [String] model: slim. Only exists when skin model is Alex. When skin model is Steve, this metadata does not exist.
          • [NBT Compound / JSON Object] CAPE: Cape texture. If the player does not have a cape, this does not exist.
            • [String] url: URL to the cape texture.

Example

https://sessionserver.mojang.com/session/minecraft/profile/853c80ef3c3749fdaa49938b674adae6
Returns:

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

Content in [String] value after Base64 decoded:

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

Error

HTTP status code	error	errorMessage	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 scope parameter should include XboxLive.signin to obtain an Xbox Live token.

Obtain an Xbox Live token with Microsoft token

Payload

• [NBT Compound / JSON Object] Root tag
  • [NBT Compound / JSON Object] Properties: Authentication properties
    • [String] AuthMethod: Login method. This should be RPS.
    • [String] SiteName: Website name. This should be user.auth.xboxlive.com.
    • [String] RpsTicket: Ticket used for logging in. Value should be d=<Microsoft access token>.
  • [String] RelyingParty: Replying party. This should be http://auth.xboxlive.com.
  • [String] TokenType: Type of the access token. This should be JWT.

Request (POST)

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

SSL renegotiation required in SSL implementation.

Response

• [NBT Compound / JSON Object] Root tag
  • [String] IssueInstant: Time when obtaining the Xbox Live token.
  • [String] NotAfter: Time the Xbox Live token is expired.
  • [String] Token: Xbox Live access token.
  • [NBT Compound / JSON Object] DisplayClaims: Unknown.
    • [NBT List / JSON Array] xui: Unknown.
      • [NBT Compound / JSON Object]
        • [String] uhs: User hashcode.

Obtain an XSTS token with Xbox Live token

Payload

• [NBT Compound / JSON Object] Root tag
  • [NBT Compound / JSON Object] Properties: Auth properties.
    • [String] SandboxId: Sandbox ID. This should be RETAIL.
    • [NBT List / JSON Array] UserTokens: User's Xbox Live token.
      • [String]: User's Xbox Live token obtained in the previous step.
  • [String] RelyingParty: Replying party. This should be rp://api.minecraftservices.com/.
  • [String] TokenType: Type of the access token. This should be JWT.

Request (POST)

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

SSL renegotiation required in SSL implementation.

Response

• [NBT Compound / JSON Object] Root tag
  • [String] IssueInstant: Time when obtaining the XSTS token.
  • [String] NotAfter: Time the XSTS token is expired.
  • [String] Token: XSTS access token.
  • [NBT Compound / JSON Object] DisplayClaims: Unknown.
    • [NBT List / JSON Array] xui: Unknown.
      • [NBT Compound / JSON Object]
        • [String] uhs: User hashcode.

Error

HTTP 401 is returned if an error occurs in obtaining the XSTS token.

Obtain Minecraft access token with XSTS token

Payload

• [NBT Compound / JSON Object] Root tag
  • [String] identityToken: Identity token. The value should be XBL3.0 x=<User hashcode>;<XSTS access token>.

Request (POST)

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

Response

• [NBT Compound / JSON Object] Root tag
  • [String] username: UUID (not the UUID for the player)
  • [NBT List / JSON Array] roles: Unknown, empty.
  • [String] access_token: Minecraft access token.
  • [String] token_type: Token type. This is always Bearer.
  • [String] 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/mcstore

Response

If the account owns Minecraft, returns:

• [NBT Compound / JSON Object] Root tag
  • [NBT List / JSON Array] items: Data and signatures.
    • [String] name: Data name, either product_minecraft or game_minecraft.
    • [String] signature: JWT signature for the data.
  • [String] signature: JWT signature.
  • [String] keyID: Unknown.

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

• [NBT Compound / JSON Object] Root tag
  • [String] id: Player's UUID.
  • [String] name: Player name.
  • [NBT List / JSON Array] skins: A list of info of all the skins the player owns.
    • [NBT Compound / JSON Object]: A skin.
      • [String] id: Cape's UUID.
      • [String] state: Usage status for the cape.
      • [String] url: URL to the skin.
      • [String] variant: Skin variant. CLASSIC for the Steve model and SLIM for the Alex model.
  • [NBT List / JSON Array] capes: A list of info of all the capes the player owns.
    • [NBT Compound / JSON Object]: A cape.
      • [String] id: Cape's UUID.
      • [String] state: Usage status for the cape.
      • [String] url: URL to the cape.
      • [String] alias: Alias for the cape.

Query player attributes

Request (GET)

/player/attributes

Response

• [NBT Compound / JSON Object] Root tag
  • [NBT Compound / JSON Object] privileges: Player's privileges
    • [NBT Compound / JSON Object] onlineChat: Privilege of accepting chat messages
      • [Boolean] enable
    • [NBT Compound / JSON Object] multiplayerServer: Privilege of joining servers.
      • [Boolean] enable
    • [NBT Compound / JSON Object] multiplayerRealms: Privilege of joining Realms.
      • [Boolean] enable
    • [NBT Compound / JSON Object] telemetry: Privilege of sending telemetry.
      • [Boolean] enable
    • [NBT Compound / JSON Object] optionalTelemetry: Privilege of sending optional telemetry.
      • [Boolean] enable
  • [NBT Compound / JSON Object] profanityFilterPreferences: Profanity filter settings.
    • [Boolean] profanityFilterOn: If Realms profanity filter is on.
  • [NBT Compound / JSON Object] banStatus: Player's ban status
    • [NBT Compound / JSON Object] bannedScopes: Scope in which the player is banned.
      • [NBT Compound / JSON Object]: Ban scope. If the player is not banned, these objects do not exist. Only MULTIPLAYER exists.
        • [String] banId: UUID of the ban.
        • [String] expires: When the ban expires. This does not exist if the player is permanently banned.
        • [String] reason: Reason for the ban.
        • [String] reasonMessage: Ban message displayed.

Modify player attributes

Payload

• [NBT Compound / JSON Object] Root tag
  • [NBT Compound / JSON Object] profanityFilterPreferences: Realms profanity filter options.
    • [Boolean] profanityFilterOn: If filter is on.

Request (POST)

/player/attributes

Response

The same as #Query player attributes.

Get list of blocked users

Request (GET)

/privacy/blocklist

Response

• [NBT Compound / JSON Object] Root tag
  • [NBT List / JSON Array] blockedProfiles: A list of blocked players whose chat messages and Realms invitations are ignored.
    • [String]: UUID for the blocked player.

Get keypair for signature

Request (POST)

/player/certificates

Response

• [NBT Compound / JSON Object] Root tag
  • [NBT Compound / JSON Object] keyPair: Keypair used for signature.
    • [String] privateKey: Private key. Starts with -----BEGIN RSA PRIVATE KEY----- and ends with -----END RSA PRIVATE KEY-----.
    • [String] publicKey: Public key. Starts with-----BEGIN RSA PUBLIC KEY----- and ends with -----END RSA PUBLIC KEY-----.
  • [String] publicKeySignature: Deprecated, see below.
  • [String] publicKeySignatureV2: Public key signature.
  • [String] expiresAt: When the keypair expires.
  • [String] refreshedAfter: When the keypair should be refreshed.

Query player's name change information

Request (GET)

/minecraft/profile/namechange

Response

• [NBT Compound / JSON Object] Root tag
  • [String] changedAt: The last time the name has been changed.
  • [String] createdAt: The time the player profile is created.
  • [Boolean] 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

Response

• [NBT Compound / JSON Object] Root tag
  • [String] status: Status of the name. DUPLICATE means the name is taken. AVAILABLE means the name is available.NOT_ALLOWED means the name does not meet requirements.

Change name

Input

Name to change to

Request (PUT)

/minecraft/profile/name/<name to change to>

Response

• [NBT Compound / JSON Object] Root tag
  • [String] id: Player's UUID.
  • [String] name: Player name.
  • [NBT List / JSON Array] skins: A list of info of all the skins the player owns.
    • [NBT Compound / JSON Object]: A skin.
      • [String] id: Cape's UUID.
      • [String] state: Usage status for the cape.
      • [String] url: URL to the skin.
      • [String] variant: Skin variant. CLASSIC for the Steve model and SLIM for the Alex model.
  • [NBT List / JSON Array] capes: A list of info of all the capes the player owns.
    • [NBT Compound / JSON Object]: A cape.
      • [String] id: Cape's UUID.
      • [String] state: Usage status for the cape.
      • [String] url: URL to the cape.
      • [String] alias: Alias for the cape.

Error

HTTP status code	error	errorMessage	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	-	-	To many rename requests sent.

Change skin

Payload

• [NBT Compound / JSON Object] Root tag
  • [String] variant: Skin variant. classic for the Steve model and slim for the Alex model.
  • [String] url: URL to the skin.

Request (POST)

/minecraft/profile/skins

Response

Returns the profile if operation succeeds.

Upload skin

Payload

Payload is made up of two parts:

• variant: Skin variant. classic for the Steve model and slim for the Alex model.
• file: Image data for the new skin. See example below.

Request (POST)

/minecraft/profile/skins

Example

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

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

• [NBT Compound / JSON Object] Root tag
  • [String] capeId: UUID for the cape to activate

Request (PUT)

/minecraft/profile/capes/active

Response

Returns the profile if operation succeeds.

Error

HTTP status code	error	errorMessage	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

• [NBT Compound / JSON Object] Root tag
  • [String] accessToken: Minecraft access token.
  • [String] selectedProfile: Player UUID without dashes.
  • [String] serverId: Server ID. See below.

Server ID is obtained from the following algorithm:

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);
}

Request (POST)

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

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

• [NBT Compound / JSON Object] Root tag
  • [NBT List / JSON Array] 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.
    • [String]: Base64-encoded DER public key.
  • [NBT List / JSON Array] 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.
    • [String]: Base64-encoded DER public key.

History

April 14, 2014							Mojang API is released.
November 2020							Endpoint for obtaining player UUID no longer supports the at parameter.
October 8, 2021							Endpoint for querying Mojang API status is removed. The endpoint was https://status.mojang.com/check.
May 8, 2022							Endpoint for querying Minecraft sales is removed. The endpoint was https://api.mojang.com/orders/statistics.
September 13, 2022							The endpoint for querying names a player used to use is removed. The endpoint was https://api.mojang.com/user/profiles/<UUID>/names.
January 15, 2025							The endpoint for querying UUIDs based on a player's name has experimental rate limits introduced. The endpoint is https://api.mojang.com/users/profiles/minecraft/<username>/names.

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