Difference between revisions of "Pocket Realms"

From wiki.vg
Jump to navigation Jump to search
(Updated information to be much more accurate to the latest Bedrock release.)
(Add note about the new bedrock realms page)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[Category:Pocket_Minecraft]]
 
[[Category:Pocket_Minecraft]]
  
−
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.
+
{{Box
 +
  |BORDER = #9999FF
 +
  |BACKGROUND = #99CCFF
 +
  |WIDTH = 100%
 +
  |ICON =
 +
  |HEADING = Heads up!
 +
  |CONTENT = This article is about the old Pocket Edition Realms service and is no longer updated. For the current realms service, see [[Bedrock Realms]].
 +
}}
 +
 
  
−
The information on this page may be incorrected and incomplete.
+
== Authentication ==
 +
 
 +
Endpoint: https://account.mojang.com
 +
 
 +
Steps to Login
 +
*Pull authenticityToken from /m/login?app=mcpe&version=0.7.6
 +
*POST to /m/login
 +
*Client is redirected to /m/launch
 +
 
 +
=== POST /m/login ===
 +
 
 +
Player Login
 +
 
 +
Parameters sent in body
 +
 
 +
Request Parameters:
 +
 
 +
*authenticityToken: Pulled from /m/login?app=mcpe&version=0.7.6
 +
*email: Email of user
 +
*password: Password of user
 +
 
 +
Pull mojangSessionId from the PLAY_SESSION cookie, and use that as the sid cookie in peoapi.minecraft.net requests. The mojangSessionId is also returned in a JSON key of sessionID with a request to /m/session
 +
 
 +
Cookies needed for peoapi.minecraft.net requests:
  
−
== Authentication ==
+
*sid: Pulled from mojangSessionId
 +
*gameversion: Version of the game the requests are coming from
  
−
Login is handled by Xbox Live, which is out of scope of this page.
+
Response:
  
−
To authenticate with the endpoints, you need an Authorization header set with an XBL-3.0 Xbox Live service token.
+
<pre>
 +
Logged in.
 +
</pre>
  
 
== Endpoints ==
 
== Endpoints ==
  
−
Server hostname: https://pocket.realms.minecraft.net
+
Endpoint: https://peoapi.minecraft.net
  
−
=== GET /mco/client/compatible ===
+
=== GET /server/list ===
  
−
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.
+
List servers that user own or has been invited to
  
−
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.
+
Response Parameters:
  
−
'''Request:'''
+
*serverId: Id of server
−
GET /mco/client/compatible HTTP/1.1
+
*name: Server Title
−
Accept: */*
+
*open: Whether server is joinable
−
Authorization: XBL3.0 [SERVICETOKEN]
+
*ownerName: Name of server owner
−
Cache-Control: no-cache
+
*myWorld: Whether the server belongs to the current user
−
Charset: utf-8
+
*maxNrPlayers: Max number of players
−
Client-Version: 1.10.1
+
*type: Type of server, can be creative or survival
−
User-Agent: MCPE/UWP
+
*playerNames: Usernames of players currently playing on the server
−
Accept-Language: en-GB
+
*invited: Usernames of players who are invited to the server
−
Accept-Encoding: gzip, deflate, br
+
*daysLeft: Unknown use
−
Host: pocket.realms.minecraft.net
 
−
Connection: Keep-Alive
 
  
−
'''Response:'''
+
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
+
    "serverId":1,
 +
    "name":"Steve's Server",
 +
    "open":true,
 +
    "ownerName":"Steve",
 +
    "myWorld":true,
 +
    "maxNrPlayers":10,
 +
    "type":"survival",
 +
    "playerNames":["Steve", "Stevie"],
 +
    "invited":["Steve", "Stevie"],
 +
    "daysLeft": 0
 +
   
 +
}]
 +
 
 +
 
 +
=== POST /server/{id}/join ===
 +
 
 +
Join a server
 +
 
 +
Request Parameters:
 +
 
 +
*id: Pulled from serverId on /server/list
 +
 
 +
Response Paramenters:
 +
 
 +
*ip: IP of server
 +
*port: Port of server
 +
*key: Key used to encrypt the data received on the server (AES-128 ECB)
 +
Response:
 +
 
 +
{
 +
    "ip":"87.169.167.12",
 +
    "port":21647,
 +
    "key":"/6UAOMG6Q/EIjHxLa87un5l=="
 +
}
 +
 
 +
 
 +
=== POST /server/create?name={server_name}&type={type}&seed={seed} ===
 +
 
 +
Create a server. (Not complete)
 +
 
 +
Request Parameters:
 +
 
 +
*server_name: Title of server
 +
*type: Type of server, can be creative or survival
 +
*seed: Seed for server
 +
Response:
 +
 
 +
Response not yet documented
 +
 
 +
 
 +
=== PUT /server/{id}/name/{server_name} ===
 +
 
 +
Change name of server (Not complete)
 +
 
 +
Request Parameters:
 +
 
 +
*id: Pulled from serverId on /server/list
 +
*server_name: Title of server
 +
Response:
 +
 
 +
Response not yet documented
 +
 
 +
 
 +
=== PUT /server/{id}/open ===
 +
 
 +
Open server (Not complete)
 +
 
 +
Request Parameters:
 +
 
 +
*id: Pulled from serverId on /server/list
 +
Response:
 +
 
 +
Response not yet documented
 +
 
 +
 
 +
=== PUT /server/{id}/close ===
 +
 
 +
Close server (Not complete)
 +
 
 +
Request Parameters:
 +
 
 +
*id: Pulled from serverId on /server/list
 +
Response:
 +
 
 +
Response not yet documented
 +
 
 +
 
 +
=== POST /server/{id}/whitelist/{username} ===
 +
 
 +
Add username to whitelist (Not complete)
 +
 
 +
Request Parameters:
 +
 
 +
*id: Pulled from serverId on /server/list
 +
*username: Username of player to add to the whitelist
 +
Response:
 +
 
 +
Response not yet documented
 +
 
  
−
=== GET /worlds ===
+
=== DELETE /server/{id}/whitelist/{username} ===
  
−
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.
+
Delete username from whitelist (Not complete)
  
−
'''Response (as JSON)'''
+
Request Parameters:
−
* '''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 '''X'''box'''U'''ser'''ID''' (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} ===
+
*id: Pulled from serverId on /server/list
 +
*username: Username of player to delete from the whitelist
 +
Response:
  
−
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 not yet documented
  
−
'''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 ===
+
=== POST /server/heartbeat?nplayers={num_players} ===
  
−
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.
+
Exact use unknown (Not complete) (Most likely a POST)
  
−
'''Request:'''
+
Request Parameters:
−
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:'''
+
*num_players: Number of players currently on server?
−
HTTP/1.1 200 OK
+
Response:
−
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 ===
+
Response not yet documented
  
−
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 /auth/validate-player/{unknown_string}/{unknown_string} ===
−
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:'''
+
Check whether username is authorized? (Not complete)
−
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
 
  
−
=== PUT /worlds/{id}/open ===
+
Needs the cookie '''key'''
  
−
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 Parameters:
  
−
'''Request:'''
+
*unknown_string: One of the values could be a username?
−
GET /worlds/[REALMID]/open HTTP/1.1
+
Response:
−
Accept: */*
+
  Response not yet documented
−
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 ===
+
=== GET /info/status ===
  
−
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.
+
Determines whether server creation is allowed
  
−
'''Request:'''
+
Response Parameters:
−
GET /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:'''
+
*buyServerEnabled: Whether server buying is enabled?
−
HTTP/1.1 200 OK
+
*createServerEnabled: Whether server creation is enabled?
−
Content-Type: text/plain
+
Response:
−
Date: Sun, 07 Apr 2019 23:52:15 GMT
 
−
X-REQUEST-ID: [REQUESTID]
 
−
Content-Length: 1
 
−
Connection: keep-alive
 
−
 
−
true
 
  
 +
{"serviceEnabled":true,"buyServerEnabled":false,"createServerEnabled":false}
  
 
[[Category: Pocket Minecraft]]
 
[[Category: Pocket Minecraft]]

Latest revision as of 12:38, 6 June 2020


Heads up!

This article is about the old Pocket Edition Realms service and is no longer updated. For the current realms service, see Bedrock Realms.


Authentication

Endpoint: https://account.mojang.com

Steps to Login

  • Pull authenticityToken from /m/login?app=mcpe&version=0.7.6
  • POST to /m/login
  • Client is redirected to /m/launch

POST /m/login

Player Login

Parameters sent in body

Request Parameters:

  • authenticityToken: Pulled from /m/login?app=mcpe&version=0.7.6
  • email: Email of user
  • password: Password of user

Pull mojangSessionId from the PLAY_SESSION cookie, and use that as the sid cookie in peoapi.minecraft.net requests. The mojangSessionId is also returned in a JSON key of sessionID with a request to /m/session

Cookies needed for peoapi.minecraft.net requests:

  • sid: Pulled from mojangSessionId
  • gameversion: Version of the game the requests are coming from

Response: 

Logged in.

Endpoints

Endpoint: https://peoapi.minecraft.net

GET /server/list

List servers that user own or has been invited to

Response Parameters:

  • serverId: Id of server
  • name: Server Title
  • open: Whether server is joinable
  • ownerName: Name of server owner
  • myWorld: Whether the server belongs to the current user
  • maxNrPlayers: Max number of players
  • type: Type of server, can be creative or survival
  • playerNames: Usernames of players currently playing on the server
  • invited: Usernames of players who are invited to the server
  • daysLeft: Unknown use

Response: 

[{

   "serverId":1,
   "name":"Steve's Server",
   "open":true,
   "ownerName":"Steve",
   "myWorld":true,
   "maxNrPlayers":10,
   "type":"survival",
   "playerNames":["Steve", "Stevie"],
   "invited":["Steve", "Stevie"],
   "daysLeft": 0

}]


POST /server/{id}/join

Join a server

Request Parameters:

  • id: Pulled from serverId on /server/list

Response Paramenters:

  • ip: IP of server
  • port: Port of server
  • key: Key used to encrypt the data received on the server (AES-128 ECB)

Response: 

{
   "ip":"87.169.167.12",
   "port":21647,
   "key":"/6UAOMG6Q/EIjHxLa87un5l=="
}


POST /server/create?name={server_name}&type={type}&seed={seed}

Create a server. (Not complete)

Request Parameters:

  • server_name: Title of server
  • type: Type of server, can be creative or survival
  • seed: Seed for server

Response: 

Response not yet documented


PUT /server/{id}/name/{server_name}

Change name of server (Not complete)

Request Parameters:

  • id: Pulled from serverId on /server/list
  • server_name: Title of server

Response: 

Response not yet documented


PUT /server/{id}/open

Open server (Not complete)

Request Parameters:

  • id: Pulled from serverId on /server/list

Response: 

Response not yet documented


PUT /server/{id}/close

Close server (Not complete)

Request Parameters:

  • id: Pulled from serverId on /server/list

Response: 

Response not yet documented


POST /server/{id}/whitelist/{username}

Add username to whitelist (Not complete)

Request Parameters:

  • id: Pulled from serverId on /server/list
  • username: Username of player to add to the whitelist

Response: 

Response not yet documented


DELETE /server/{id}/whitelist/{username}

Delete username from whitelist (Not complete)

Request Parameters:

  • id: Pulled from serverId on /server/list
  • username: Username of player to delete from the whitelist

Response: 

Response not yet documented


POST /server/heartbeat?nplayers={num_players}

Exact use unknown (Not complete) (Most likely a POST)

Request Parameters:

  • num_players: Number of players currently on server?

Response: 

Response not yet documented


GET /auth/validate-player/{unknown_string}/{unknown_string}

Check whether username is authorized? (Not complete)

Needs the cookie key

Request Parameters:

  • unknown_string: One of the values could be a username?

Response: 

Response not yet documented


GET /info/status

Determines whether server creation is allowed

Response Parameters:

  • buyServerEnabled: Whether server buying is enabled?
  • createServerEnabled: Whether server creation is enabled?

Response: 

{"serviceEnabled":true,"buyServerEnabled":false,"createServerEnabled":false}
Retrieved from "https://wiki.vg/index.php?title=Pocket_Realms&oldid=15745"