Toggle search
Toggle menu
20.8K
1.7K
7
111.7K
SAS Gaming Wiki
Toggle preferences menu
Toggle personal menu
Not logged in
Your IP address will be publicly visible if you make any edits.

Minecraft:Mojang API

From SAS Gaming Wiki
More actions
Revision as of 11:18, 16 May 2026 by SyncBot (talk | contribs) (Sync: updated from Minecraft)

This page provides documentation for API endpoints provided by Minecraft: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-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:

These are some common causes:

HTTP status code Template:Cd Template:Cd 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.
Template:Tc 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:Cd 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)
Response
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/minecraft
  • https://api.minecraftservices.com/minecraft/profile/lookup/bulk/byname
  • https://api.mojang.com/minecraft/profile/lookup/bulk/byname
Response
Example

Request with payload ["jeb_","notch"]. <syntaxhighlight lang="json">[ 

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

]</syntaxhighlight>

HTTP status code Template:Cd Template:Cd 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
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 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 Template:Cd Template:Cd 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

Template:For

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 Template:Cd parameter should include Template:Samp to obtain an Xbox Live token.

Obtain an Xbox Live token with Microsoft token

Payload
Request (POST)

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

SSL renegotiation required in SSL implementation.

Response

Obtain an XSTS token with Xbox Live token

Payload
Request (POST)

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

SSL renegotiation required in SSL implementation.

Response
Error

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

Obtain Minecraft access token with XSTS token

Payload
Request (POST)

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

Response

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:

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

Query player attributes

Request (GET)

/player/attributes

Response

Modify player attributes

Payload

A JSON array containing the desired keys to update, right now, only orofanityFilterPreferences and friendsPreferences can be updated

Request (POST)

/player/attributes

Response

The same as #Query player attributes.

Get list of blocked users

Request (GET)

/privacy/blocklist

Response

Get keypair for signature

Request (POST)

/player/certificates

Response

Query player's name change information

Request (GET)

/minecraft/profile/namechange

Response

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 Root tag
    • Template:Nbt: 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
Error
HTTP status code Template:Cd Template:Cd 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
Request (POST)

/minecraft/profile/skins

Response

Returns the profile if operation succeeds.

Upload skin

Payload

Payload is made up of two parts:

  • Template:Cd: Skin variant. classic for the Steve model and slim for the Alex model.
  • Template:Cd: 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
Request (PUT)

/minecraft/profile/capes/active

Response

Returns the profile if operation succeeds.

Error
HTTP status code Template:Cd Template:Cd 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

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 Root tag
    • Template:Nbt: 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: 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: A list of public keys used for verifying authentication tokens, like the JWT access token used in the Authorization Header in most requests to the Minecraft API.

Friends list

The friends list was introduced in Minecraft Java Edition 26.2 Snapshot 7. The API and client behavior are as such unstable and likely to change.

These endpoints are located on https://api.minecraftservices.com, and all require the Authorization header to be provided in the request with a value of Bearer <Minecraft access token>. An HTTP 401 error is returned if the token is missing or invalid.

Get list of friends and friend requests

Request (GET)

/friends

You may send an optional If-None-Match request header. See below for details.

Response

The response has an ETag response header, which you may save and reuse as the value for filling the If-None-Match request header in further requests.

If the friends list has not changed since the last request, and the value of the If-None-Match request header matches the value of the ETag response header in the last request, Mojang will return a HTTP 304 Not Modified response.

Example

<syntaxhighlight lang="json"> { 

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

} </syntaxhighlight>

Friend management

Request (PUT)

/friends

Payload
  • Template:Nbt
    • Template:Nbt: Profile name of the player to add or remove. Optional.
    • Template:Nbt: UUID of the player to add or remove, Optional.
    • Template:Nbt: Action to perform. Values: ADD for sending or accepting friend requests, REMOVE for removing friends or denying friend requests.

name and profileId are optional, but at least one must be provided. If both are present, profileId will be prioritized.

Example

<syntaxhighlight lang="json"> { 

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

} </syntaxhighlight>

Response

Identical to #Get list of friends and friend requests.

Error
HTTP status code Template:Cd Template:Cd Explanation
400 UNKNOWN_PROFILE Name or profile does not exist
CANNOT_ADD_SELF Cannot add yourself as friend
NOT_FRIENDS Not friend with Template:Cd cannot remove
ALREADY_FRIENDS Already friend with Template:Cd
INVALID_JSON Depends on request body All arguments required presents in request body, but somehow cannot be decoded (e.g. wrong enum values, invalid UUID)
CONSTRAINT_VIOLATION Depends on request body Some required arguments is missing
403 INVITE_REJECTED User does not have friends enabled or accept invites

Presence

This API is used for both querying friends' presences and reporting your current presence status. There is no standalone API for querying friends' presences.

Request (POST)

/presence

Payload
  • Template:Nbt
    • Template:Nbt: Your current presence status. See the table below for all available statuses.
    • Template:Nbt: Information relating to peer-to-peer multiplayer invites. Should be omitted in certain situations, see below.
      • Template:Nbt: The 26.2-snapshot-7 client always sends null. See below.
      • Template:Nbt: List of UUIDs which are invited. Must be UUID with dashes. Optional.

For all presence statuses you may choose to omit the entire joinInfo object, even while reporting a PLAYING_HOSTED_SERVER status. The recipient's game client won't show "Request to join world" button in this situation. This is likely unintended behavior, and is subject to change in the near future.

To report an OFFLINE, ONLINE, PLAYING_OFFLINE or PLAYING_SERVER status, you must have a string (1 <= length <= 256) or a numeric joinInfo.value present or omit the entire joinInfo object, otherwise Mojang will return a HTTP 400 Bad Request response.

To report a PLAYING_HOSTED_SERVER status, you must have a null joinInfo.value present or omit the entire joinInfo object, otherwise Mojang will return a HTTP 400 Bad Request response.

To report a PLAYING_REALMS status, you must have a numeric joinInfo.value present or omit the entire joinInfo object, otherwise Mojang will return a HTTP 400 Bad Request response.

You can add non-friends (even dummy UUIDs, such as all zeroes) to joinInfo.invites, and Mojang will not return an error. However, since you're not friends, you won't appear in their friends list, so they won't receive your peer-to-peer multiplayer invite.

Response
  • Template:Nbt
    • Template:Nbt: List of presence statuses. Only online friends will be included within this list.
      • Template:Nbt: UUID of the player, with dashes.
      • Template:Nbt: PMID used in peer-to-peer multiplayer. UUID with dashes.
      • Template:Nbt: Player's presence status. See the table below for all available statuses.
      • Template:Nbt: May be omitted in certain situations, see below.
        • Template:Nbt: Typically the same as the PMID, but can also be other values.
        • Template:Nbt: Whether you are invited to join the peer-to-peer multiplayer session.
      • Template:Nbt: Timestamp of the most recent presence report from this player.

joinInfo will be omitted if your friends omitted it when reporting their presence. This should not happen in vanilla Minecraft clients.

For most cases joinInfo.value should be same as the PMID, but could also be something else if your friends send a non-null value while reporting their presences. This shouldn't happen in vanilla Minecraft clients. The meaning of this key is unclear, since the 26.2-snapshot-7 client ignores it.

joinInfo.invited could be true when status is ONLINE. This means your friend set "Presence: LIMITED" in their settings, which restricts the status to reporting either ONLINE or OFFLINE, while still allowing them to invite others to join their peer-to-peer multiplayer session.

Currently, the game client doesn't seem to report the OFFLINE status before shutting down. After 10 minutes the server will consider the player offline due to their lack of presence updates.

All available presence statuses
Template:Cd Text shows on UI Explanation Comment
OFFLINE Offline The player is offline Offline players won't appear in their friends' presence responses
ONLINE Online The player is online but not playing any world or server (e.g. idling on the main menu, tweaking settings, etc.) If the player set "Presence: LIMITED" in settings, the game will always report this
PLAYING_OFFLINE In a world The player is playing a world which isn't open to peer-to-peer multiplayer (Multiplayer set to "OFF" or "LAN")
PLAYING_HOSTED_SERVER In a joinable world The player is playing a world which is open to peer-to-peer multiplayer
PLAYING_REALMS In a Realm The player is playing a Realms server 26.2-snapshot-7 will not report this
PLAYING_SERVER On a server The player is playing on a third-party server 26.2-snapshot-7 will not report this
Error

Nearly identical to #Friends management, with only INVALID_JSON and CONSTRAINT_VIOLATION present. If you have joinInfo.value present but violate the rules mentioned above, Mojang will return a HTTP 400 Bad Request error with only path and errorMessage.

Example request

<syntaxhighlight lang="json"> { 

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

} </syntaxhighlight>

Example response

<syntaxhighlight lang="json"> { 

 "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"
   }
 ]

} </syntaxhighlight>

History

Template:HistoryTable

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

Template:Reflist

Navigation

Template:Navbox Java Edition technical Template:License wiki.vg

Minecraft:de:Mojang API Minecraft:lzh:魔贊卯口 Minecraft:zh:Mojang API

Retrieved from "https://wiki.sasgaming.net/index.php?title=Minecraft:Mojang_API&oldid=117879"
Contents