Skip to content

Discovery

All this info is accurate as of MCEDU v1.21.10. This doesn't follow an order. I'm 50% sure almost all of these need the header User-Agent:libhttpclient/1.0.0.0 to work.

Host

  • Sends a post request to https://discovery.minecrafteduservices.com/host to host a game using the join code system. Join codes you make only work in your organization. You need the MS Access Token from startup. You also need the nethernetID, a uint64. You can randomly generate it now, but you should already have it from when you established a Secure Websocket with the signaling server wss://signal.franchise.minecraft-services.net/ws/v1.0/signaling/[insert nethernetID].
  • You'll get the server token and the join code number from this. The join code you get could be four, five, or six symbols long.
Click to view request/response structure
Request Response 
Body:


{
    "accessToken": "[insert MSFT ACCESS Token]",
    "build": 12110000,
    "locale": "en_US",
    "maxPlayers": 40,
    "networkId": "[insert nethernetID as string]",
    "playerCount": 1,
    "protocolVersion": 1,
    "serverDetails": "Username",
    "serverName": "My World",
    "transportType": 2
}
Body: 
{
    "serverToken": "tenantID|MSUserID|UTCTimestamp|256character long string of lowercase letters & numbers",
    "passcode": "10,13,5,1,17"
}

Update

  • It sends a post request to https://discovery.minecrafteduservices.com/update. It doesn't return anything, and is just for updating the data Discovery has about your world.
Click to view request/response structure
Request Response 
  {
    "build": 12110000,
    "locale": "en_US",
    "maxPlayers": 40,
    "passcode": "[insert joincode string]",
    "playerCount": 1,
    "protocolVersion": 1,
    "serverDetails": "Username",
    "serverName": "My World",
    "serverToken": "[insert server token]"
  }
Empty body unless error.

Dehost/Heartbeat

  • Sends a post request to https://discovery.minecrafteduservices.com/dehost to take your game off the discovery service. It deletes your passcode. Your websocket can still continue running even if you turn off the discovery service. However, if you do this, people can still join directly using the nethernetID. It returns nothing unless it made a mistake.

  • Sends a post request to https://discovery.minecrafteduservices.com/heartbeat. It just makes sure that the game doesn't expire off the discovery system. This allows it to retain its join code. It returns nothing unless you made a mistake. There is data in the EDUTOKEN that tells you how often you have to send heartbeat requests. If you can't decode a JWT, just do it every 100 seconds.

  • Both the dehost & heartbeat requests send the same data & have the same responses.

Click to view request/response structure
Request Response 
Body:


{
    "build": 12110000,
    "locale": "en_US",
    "passcode": "[insert joincode string]",
    "protocolVersion": 1,
    "serverToken": "[insert server token]"
}
Empty body unless error

Join Info

  • It sends a post request to https://discovery.minecrafteduservices.com/joininfo. This is a kind of query that is used to check whether a join code string has a valid server in your organization. You will need an MS access token. It returns data about the server if it links to a valid server, the most important being the nethernetID.
Click to view request/response structure
Request Response 
Body:


{
    "accessToken": "[insert MSFT Access Token]",
    "build": 12110000,
    "locale": "en_US",
    "passcode": "[insert joincode string]",
    "protocolVersion": 1
}
Body: 
{
    "connectionInfo": {
        "info": {
            "id": "[insert nethernetID as string]"
        },
        "transportType": 2
    },
    "serverDetails": "Username",
    "serverName": "My World"
}

Change Join Code

  • To change the join code, just do a dehost request and immediately after a host request. This is how the game does it and how you will too.
  • This is so simple I feel stupid for not figure this out sooner. Take the join code string, like 16,5,6,12,11 and encrypt it in Base64. This gives me MTYsNSw2LDEyLDEx. There is the direct & indirect way of making the link. The indirect link is https://education.minecraft.net/joinworld/MTYsNSw2LDEyLDEx. The direct link is minecraftedu://?joinworld=MTYsNSw2LDEyLDEx. All that happens is that the game decodes it from Base64, punches in the symbols for you and asks whether you want to join. The link does invalidate if you change the join code, so just don't change it.