Bedrock Realms

This page was created using information from Minecraft 1.10.1 on Windows 10. The process is (presumably) similar for Minecraft on Nintendo Switch, iOS, Android and Xbox One.

The information on this page may be incorrected and incomplete.

Authentication

Login is handled by Xbox Live, which is out of scope of this page.

To authenticate with the endpoints, you need an Authorization header set with an XBL-3.0 Xbox Live service token.

Endpoints

Server hostname: https://pocket.realms.minecraft.net

GET /mco/client/compatible

Checks whether the current version is compatible with Minecraft Realms (usually reserved for the latest version). A `Client-Version` header must be set with the version of the game and a `User-Agent` header of the edition of the game. This is requested whenever the game is launched with an active internet connection and when logged in to Xbox Live.

This endpoint returns COMPATIBLE when the version is compatible, else it returns OUTDATED when the version is either outdated or a beta version is being used.

Request:

GET /mco/client/compatible HTTP/1.1
Accept: */*
Authorization: XBL3.0 [SERVICETOKEN]
Cache-Control: no-cache
Charset: utf-8
Client-Version: 1.10.1
User-Agent: MCPE/UWP
Accept-Language: en-GB
Accept-Encoding: gzip, deflate, br
Host: pocket.realms.minecraft.net
Connection: Keep-Alive

Response:

HTTP/1.1 200 OK
Content-Type: text/plain
Date: Sun, 07 Apr 2019 23:24:59 GMT
X-REQUEST-ID: [REQUESTID]
Content-Length: 10
Connection: keep-alive

COMPATIBLE

GET /worlds

Gets a list of realms the current Xbox Live user has access to. This is requested on every tab change and load of the "Play" screen. A `Client-Version` header and a `User-Agent` header must be sent with the request, however this is not verified.

Response (as JSON)

• servers - An array containing every realm object.
  • id - The ID of the realm as an integer.
  • remoteSubscriptionId - The subscription ID of the realm as a string. (unknown purpose)
  • owner - This is always an empty string.
  • ownerUUID - The XboxUserID (XUID) of the owner as a string.
  • name - The name of the Realm as a string.
  • motd - This is always an empty string. (unknown usage).
  • defaultPermission - The default permission level of the Realm world. ("MEMBER" by default)
  • state - The state of the realm as a string. ("OPEN" or "CLOSED")
  • daysLeft - The days remaining before renewal of the Realm as an integer. (always 0 for Realms where the current user is not the owner)
  • expired - A boolean value of whether the Realm is expired or not.
  • expiredTrial - A boolean value of whether the Realm has expired as a trial or not.
  • gracePeriod - A boolean value of whether the Realm is in its grace period after expiry or not.
  • worldType - The world type of the currently loaded world ("NORMAL" by default)
  • players - Always null. (TODO: is it?)
  • maxPlayers - The maximum simultaneous player count of the Realm. (Integer, either 2 or 10)
  • minigameName - Unused, always null.
  • minigameId - Unused, always null.
  • minigameImage - Unused, always null.
  • activeSlot - The selected world slot from the realm, unused, always set to 1.
  • slots - Unknown, always null.
  • member - Unknown, always false. (even when member or owner)
  • clubId - The ID of the associated Xbox Live club as an integer.

GET /worlds/{id}

Gets information about the Realm and world specified in the URL. Returns a 403 error if the current user is not the owner of the Realm. A `Client-Version` header and a `User-Agent` header must be sent with the request, however this is not verified.

Response (as JSON):

• id - The ID of the realm as an integer.
• remoteSubscriptionId - The subscription ID of the realm as a string. (unknown purpose)
• owner - This is always an empty string.
• ownerUUID - The XUID of the owner as a string.
• name - The name of the Realm as a string.
• motd - This is always an empty string. (unknown usage).
• defaultPermission - The default permission level of the Realm world. ("MEMBER" by default)
• state - The state of the realm as a string. ("OPEN" or "CLOSED")
• daysLeft - The days remaining before renewal of the Realm as an integer. (always 0 for Realms where the current user is not the owner)
• expired - A boolean value of whether the Realm is expired or not.
• expiredTrial - A boolean value of whether the Realm has expired as a trial or not.
• gracePeriod - A boolean value of whether the Realm is in its grace period after expiry or not.
• worldType - The world type of the currently loaded world ("NORMAL" by default)
• players - An array containing all of the players who have been invited to the Realm, minus the owner.
  • uuid - The XUID of the player as a string.
  • name - Unknown, always null in testing. (Could change once player joins, untested)
  • operator - A boolean value of whether the player is an operator of the Realm or not.
  • accepted - A boolean value of whether the player has accepted the pending invite request.
  • online - A boolean value of whether the player is online on the realm.
  • permission - The permission value of the player as a string. ("MEMBER" by default)
• maxPlayers - The maximum simultaneous player count of the Realm. (Integer, either 2 or 10)
• minigameName - Unused, always null.
• minigameId - Unused, always null.
• minigameImage - Unused, always null.
• activeSlot - The selected world slot from the Realm, unused, always set to 1.
• slots - An array containing information on all the slots on the Realm.
  • options - A string containing JSON information on the world. (TODO: document data on this)
• member - Unknown, always false. (even when member or owner)
• clubId - The ID of the associated Xbox Live club as an integer.

GET /server/{id}/join

Gets the IP address and port of the Realm dedicated server specified in the URL. This is requested whenever the game attempts to load a Realm. Returns 403 if the current user doesn't have permission for that Realm. A `Client-Version` header and a `User-Agent` header must be sent with the request, however this is not verified.

Request:

GET https://pocket.realms.minecraft.net/worlds/[REALMID]/join HTTP/1.1
Accept: */*
Authorization: XBL3.0 [SERVICETOKEN]
Cache-Control: no-cache
Charset: utf-8
Client-Version: 1.8.2
User-Agent: MCPE/UWP
Accept-Language: en-GB
Accept-Encoding: gzip, deflate, br
Host: pocket.realms.minecraft.net
Connection: Keep-Alive

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 08 Apr 2019 00:02:05 GMT
X-REQUEST-ID: [REQUESTID]
Content-Length: 91
Connection: keep-alive

{"address":"[server address on amazonaws.com]:[realm port]","pendingUpdate":true}

GET /invites/count/pending

Gets the amount of pending Realm invites of the currently logged in Xbox Live user. The game periodically requests this while on the main menu of the game. The response is returned as an integer. A `Client-Version` header and a `User-Agent` header must be sent with the request, however this is not verified.

Request:

GET /invites/count/pending HTTP/1.1
Accept: */*
Authorization: XBL3.0 [SERVICETOKEN]
Cache-Control: no-cache
Charset: utf-8
Client-Version: 1.10.1
User-Agent: MCPE/UWP
Accept-Language: en-GB
Accept-Encoding: gzip, deflate, br
Host: pocket.realms.minecraft.net
Connection: Keep-Alive

Response:

HTTP/1.1 200 OK
Content-Type: text/plain
Date: Sun, 07 Apr 2019 23:52:15 GMT
X-REQUEST-ID: [REQUESTID]
Content-Length: 1
Connection: keep-alive

0

GET /world/{id}/content/

Request:

GET /world/[REALMID]/content/ HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net  

Response:

{
   "worldId": Integer,
   "name": String,
   "resourcePacks": [
       {
           "packId": String,
           "version": String
       },
       {
           "packId": String,
           "version": String
       }
   ],
   "behaviorPacks": [
       {
           "packId": String,
           "version": String
       }
   ]
}

PUT /worlds/{id}/open

Opens the specified Realm to all invited users and allows connections. Returns 403 if the current user is not the owner of the Realm. The response is true if the action is successful, and false otherwise. A `Client-Version` header and a `User-Agent` header must be sent with the request, however this is not verified.

Request:

PUT /worlds/[REALMID]/open HTTP/1.1
Accept: */*
Authorization: XBL3.0 [SERVICETOKEN]
Cache-Control: no-cache
Charset: utf-8
Client-Version: 1.10.1
User-Agent: MCPE/UWP
Accept-Language: en-GB
Accept-Encoding: gzip, deflate, br
Host: pocket.realms.minecraft.net
Content-Length: 0
Connection: Keep-Alive

Response:

HTTP/1.1 200 OK
Content-Type: text/plain
Date: Sun, 07 Apr 2019 23:52:15 GMT
X-REQUEST-ID: [REQUESTID]
Content-Length: 1
Connection: keep-alive

true

PUT /worlds/{id}/close

Closes the specified Realm and disables all new connections to the server. Returns 403 if the current user is not the owner of the Realm. The response is true if the action is successful, and false otherwise. A `Client-Version` header and a `User-Agent` header must be sent with the request, however this is not verified.

Request:

PUT /worlds/[REALMID]/close HTTP/1.1
Accept: */*
Authorization: XBL3.0 [SERVICETOKEN]
Cache-Control: no-cache
Charset: utf-8
Client-Version: 1.10.1
User-Agent: MCPE/UWP
Accept-Language: en-GB
Accept-Encoding: gzip, deflate, br
Host: pocket.realms.minecraft.net
Content-Length: 0
Connection: Keep-Alive

Response:

HTTP/1.1 200 OK
Content-Type: text/plain
Date: Sun, 07 Apr 2019 23:52:15 GMT
X-REQUEST-ID: [REQUESTID]
Content-Length: 1
Connection: keep-alive

true