13. The instance API
These calls start, check, list and remove on-demand game servers. They spend credits, so they need a key that can manage instances, and the request body is part of the signature.
Get a key
Choose one:
| Caller | Credentials |
|---|---|
| A master on MultiConnectCloud | No key needed. Use MC_CONTAINER_ID and MC_MASTER_TOKEN from its environment (Script 13.3). MultiConnectSDK does this by itself |
| Your own backend | An access key with Manage instances turned on |
To create the key:
- On Access Keys, click Create Access Key and turn on Manage instances. It cannot be combined with Client-distributable. Copy the Access Key and Secret.
- Open your deployment from the dashboard, and attach the key on its Access Keys panel. Attached keys that can manage instances show Manages instances.
Keep this key on your servers. Never put it in a game client.
Signing
The headers are the same as the connection lookup (Section 9), but X-MC-Signature also covers the body:
{key}:{timestamp}:{nonce}:{path}:{bodyHash}
{bodyHash} is the lowercase hex SHA-256 of the exact bytes you send as the body.
Calls
All are POST to https://api.multiconnectcloud.com.
| Path | Body | Does |
|---|---|---|
/api/PublicNew/ServerDeployments/CreateInstance |
See below | Starts one instance and returns it at once |
/api/PublicNew/ServerDeployments/GetInstance |
deploymentId, instanceId |
Returns one instance. Poll it until state is Ready |
/api/PublicNew/ServerDeployments/ListInstances |
deploymentId, optional tag, optional includeRemovedMinutes (0 to 60) |
Every live instance, plus those removed in the last N minutes. Also returns liveCount and maxInstances. Call it when your master starts, to adopt instances still mid-match |
/api/PublicNew/ServerDeployments/RemoveInstance |
deploymentId, instanceId |
Removes an instance. Billing stops now. Removing one that already ended succeeds and says how it ended |
CreateInstance body:
| Field | Meaning |
|---|---|
deploymentId |
Your deployment's id |
regionId |
Optional. A worker region. Without it, the first worker region with room is used, in the order the regions were set up |
tag |
Optional, up to 64 characters. Your label, usually a match id. The instance reads it as MC_INSTANCE_TAG |
requestId |
Optional, up to 64 characters. Retrying with the same value returns the instance the first call created, instead of starting a second |
environment |
Optional. Up to 16 { "key", "value" } pairs for this instance only. Names use upper-case letters, digits and underscores, up to 64 characters, not starting with a digit. Not MC_*, PORT, or a name already set on the deployment. Values up to 1,024 characters, plain text |
maxLifetimeMinutes |
Optional. Shorter than the deployment's maximum, if you want |
Each instance has instanceId, tag, regionId, region, state, host, port, wsUrl, transport, buildVersion, createdAt, readyAt, expiresAt, removedAt, removedReason, exitCode, errorMessage and environment.
Script 13.1: Start an instance with an access key (bash)
KEY="your-access-key"
SECRET="your-secret"
URL_PATH="/api/PublicNew/ServerDeployments/CreateInstance"
BODY='{"deploymentId":"k3J9aQ2xV0mP","tag":"match-8812","requestId":"match-8812-start","environment":[{"key":"GAME_MODE","value":"br100"}]}'
TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.* //')
SIG=$(printf '%s' "$KEY:$TS:$NONCE:$URL_PATH:$BODY_HASH" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -s -X POST "https://api.multiconnectcloud.com$URL_PATH" \
-H "Content-Type: application/json" \
-H "X-MC-Key: $KEY" -H "X-MC-Timestamp: $TS" -H "X-MC-Nonce: $NONCE" -H "X-MC-Signature: $SIG" \
-d "$BODY"
Script 13.2: The answer to Script 13.1 (trimmed)
{
"status": true,
"message": "Instance created. Poll GetInstance until it is Ready.",
"isExisting": false,
"instance": {
"instanceId": "Zr81bTq0LwE4",
"tag": "match-8812",
"regionId": 1,
"region": "India",
"state": "Starting",
"host": "203.0.113.42",
"port": 41206,
"wsUrl": null,
"transport": "TCP + UDP",
"environment": [ { "key": "GAME_MODE", "value": "br100" } ]
}
}
Script 13.3: Start an instance from a master on MultiConnectCloud, with no access key (bash)
curl -s -X POST "https://api.multiconnectcloud.com/api/PublicNew/ServerMaster/CreateInstance" \
-H "Content-Type: application/json" \
-H "X-MC-Container: $MC_CONTAINER_ID" \
-H "X-MC-Master-Token: $MC_MASTER_TOKEN" \
-d '{"tag":"match-8812","requestId":"match-8812-start"}'
The master token works for CreateInstance, GetInstance, ListInstances, RemoveInstance and GetWorkerServerInfo under /api/PublicNew/ServerMaster/, always for the master's own deployment.

