Eli: /* Connect to world */

2026-09-18T01:49:11Z

Connect to world

← Older revision		Revision as of 21:49, 17 September 2026
Line 77:		Line 77:
	** <code>badName</code>: The nickname is already taken		** <code>badName</code>: The nickname is already taken
	** <code>illegalName</code>: Nickname too long or contains illegal characters		** <code>illegalName</code>: Nickname too long or contains illegal characters
	** <code>bannedName</code>: Nickname is banned		** <code>bannedName</code>: Nickname is banned (Unknown when or why this would ever be used)
	** <code>unavailable</code>: World is unavailable due to server error		** <code>unavailable</code>: World is unavailable due to server error
	** <code>maintenance</code>: World is unavailable due to server maintenance		** <code>maintenance</code>: World is unavailable due to server maintenance

Eli: pretty much just pasting from my github here but feels like a good thing to have on the wiki

2026-09-18T01:47:00Z

pretty much just pasting from my github here but feels like a good thing to have on the wiki

New page

{{Work in progress|Document the create world endpoint}}

The now-defunct Blockheads Cloud used an HTTP API for communication between the client and server. This page documents its endpoints.

= Authentication =

The API uses a very insecure method of "authentication", which is detailed below.

== Challenge ==

All cloud sessions start with the client making a POST request to the <code>https://cloud.theblockheads.net/api/challenge</code> endpoint, containing the following URL-encoded fields:

* <code>version</code>: The version of the Blockheads client.

The server responds with a JSON object containing the following properties:

* <code>status</code>: Must be <code>ok</code> for a successful request. <code>badVersion</code> indicates that the client version is not supported. The client will show a generic error for any other value.
* <code>baseUrl</code>: The base URL to be used for future API requests.
* <code>authToken</code>: An arbitrary string chosen by the server. The client will use it in the method described below.

== Authenticate ==

The client will now make a POST request to <code>${baseUrl}/authenticate</code> containing the following URL-encoded fields:

* <code>appVersion</code>: The version of the Blockheads client.
* <code>authKey</code>: The client encodes this as follows:
** Take the static string <code><nowiki>-AcwL&jt#qWhq%dlo^xRAaTlCkQt$kgl</nowiki></code>
** Append the user's iCloud account ID (TODO: what value is used on android?)
** Append the <code>authToken</code> from the challenge response
** Hash to MD5
* <code>crystals</code>: The amount of time crystals the user has (integer).
* <code>dId</code>: The user's device ID
* <code>forceBeta</code>: Unknown what exactly this means, but the client seems to always send <code>true</code>
* <code>icId</code>: The user's iCloud ID
* <code>platform</code>: Can be <code>iOS</code> or <code>Android/Google Play</code>. The game was on the Amazon app store at one point so there could be a value for that too.

The server responds with a JSON object containing the following properties:

* <code>status</code>: Must be <code>ok</code> for a successful request. <code>banned</code> indicates that the user is cloud-banned. The client will show a generic error for any other value.
* <code>sId</code>: The session ID. Arbitrary and server-chosen
* <code>spId</code>: The user's support ID. Arbitrary and server-chosen; the official cloud used a 6-character alphabetic string. The client does not enforce this.

= Worlds =

== Search Worlds / Random World ==

The same endpoint is used for both searching and the Random World button.

The client sends a POST request to <code>${baseUrl}/world/search</code> with the following fields:

* <code>sId</code>: The session ID from the authentication response
* <code>name</code>: The string to search for in the world name. If omitted, the client is requesting a random world.
* <code>pvp</code>: If specified, only return worlds with PVP enabled (<code>true</code>) or disabled (<code>false</code>)
* <code>custom</code>: If specified, only return worlds with custom rules enabled (<code>true</code>) or disabled (<code>false</code>)
* <code>expert</code>: If specified, only return worlds with expert mode enabled (<code>true</code>) or disabled (<code>false</code>)
* <code>wIds</code> (array): Request specific worlds by ID. Cannot be used with any of the other options except <code>sId</code>. This is used to update information about worlds in the client's cache.

The server responds with a JSON object containing the following properties:

* <code>status</code>: Must be <code>ok</code> for a successful request.
* <code>worlds</code>: JSON array, containing an object for each world returned with the following fields:
** <code>wId</code>The world ID. The client does not care if this is a string or integer.
** <code>name</code>: The name of the world
** <code>players</code>: The number of players currently connected to the world

== Connect to world ==

The client sends a POST request to <code>${baseUrl}/world/connect</code> with the following fields:

* <code>sId</code>: The session ID from the authentication response
* <code>wId</code>: The world ID to connect to
* <code>name</code>: The nickname the client wants to use

The server responds with a JSON object containing the following properties:

* <code>status</code>: Must be <code>ok</code> for a successful request. Other values:
** <code>badName</code>: The nickname is already taken
** <code>illegalName</code>: Nickname too long or contains illegal characters
** <code>bannedName</code>: Nickname is banned
** <code>unavailable</code>: World is unavailable due to server error
** <code>maintenance</code>: World is unavailable due to server maintenance
** <code>noTime</code>: World has no credit
** <code>startup</code> The server must be started. The client waits 2 seconds and tries again.
* <code>ip</code>: The IP address of the server hosting the world
* <code>port</code>: The port the world is hosted on
* <code>key</code>: The key for the client to use when connecting to the world. Used to validate that the user is authenticated to their nickname. Generated as follows:
** Take the string given to the server binary in the <code>--cloud_salt</code> parameter
** Append the user's alias
** Hash to MD5

Cloud API - Revision history

Eli: /* Connect to world */

Eli: pretty much just pasting from my github here but feels like a good thing to have on the wiki