Getting Started with the Multiplayer API

What you're building

By the end of this guide you will have: an API token that identifies your game, one registered player with a stored credential, a game room that other players can join, and the exact response shape the API returns at every step. The same three calls — register, create room, join room — are the foundation every integration builds on, whether you use an official SDK or plain HTTP.

The API is a hosted backend, not a game server you deploy. Your game client talks to api.michitai.com over HTTPS for accounts, rooms, matchmaking, leaderboards and friends, and to a separate realtime relay over WebSocket for live in-room traffic. There is nothing to install server-side — the only thing you ship is client code.

Choose your path: raw curl below works everywhere; official SDKs exist for Unity, .NET, Java, Python, C++ and JavaScript/TypeScript.

1. Get your API token

Every request carries your game's public API token in the X-Api-Token header. It identifies which game the call belongs to — it is not a secret in the cryptographic sense, but treat it as a stable credential and don't commit it to public repos.

1. Register a free developer account (or sign in).
2. Open the developer cabinet and create a game.
3. Copy the API token. The cabinet also issues a private token — keep that one on your own server only; it unlocks admin calls like bans and game-data writes and must never ship inside a client.

In the examples below, replace API_TOKEN with your token. Credentials always travel in headers — never in URLs, query strings or request bodies.

2. Register a player

Player registration is the one call that needs only the API token. It creates an account inside your game and returns a private_key — the player's personal credential, sent as X-Game-Player-Token on every player-scoped call afterwards. Store it on the device (or your backend); the API does not show it again.

curl -X POST "https://api.michitai.com/api/game_players.php/register" \
  -H "X-Api-Token: API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"player_name": "PlayerOne", "player_data": {"level": 1}}'

{
  "success": true,
  "player_id": 12345,
  "private_key": "STORE-THIS-PLAYER-TOKEN",
  "player_tag": "PlayerOne#7f3a"
}

The player_tag (name + discriminator) is what friends use to look each other up. Names are screened against your game's name rules and the moderation pipeline — see Moderation.

3. Create a room

Rooms are the unit of play: lobbies, matches, persistent sessions. Creating one requires the player token from step 2 — the creator becomes the host. Set realtime to open the room for the WebSocket/UDP realtime channel.

curl -X POST "https://api.michitai.com/api/game_room.php/create" \
  -H "X-Api-Token: API_TOKEN" \
  -H "X-Game-Player-Token: PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"room_name": "Lobby 1", "max_players": 4, "realtime": true}'

The response carries the room_id other clients pass to /api/game_room.php/{room_id}/join. Full field list and host controls live in Game Rooms.

4. The same flow in an SDK

Every official SDK wraps the exact calls above. JavaScript/TypeScript:

import { MultiplayerClient } from 'michitai-multiplayer';

const mp = new MultiplayerClient('API_TOKEN');
const reg = await mp.players.register('PlayerOne', { playerData: { level: 1 } });
const playerToken = reg.private_key;              // store it
const room = await mp.rooms.create(playerToken, 'Lobby 1',
  { maxPlayers: 4, realtime: true });
if (!room.success) console.error(room.error);

Python:

from multiplayer import Client

client = Client("API_TOKEN")
reg = client.players.register("PlayerOne", {"level": 1})
player_token = reg.private_key                    # store it
room = client.rooms.create(player_token, "Lobby 1", max_players=4)

C# (Unity/.NET) and Java follow the same shape — see each SDK's documentation for its client constructor and conventions.

5. Read the response contract

Every endpoint returns JSON with a success flag. On failure the body is {"success": false, "error": "message"} paired with a 4xx/5xx status — 401 for missing or invalid tokens, 403 for wrong-scope credentials, 429 for rate limits. SDK calls return this object rather than throwing, so error handling is a check, not a catch.

The complete error catalogue with causes and fixes is in Errors; the auth model in Authentication.