Public API and webhooks

Live connection details, from your own code

Servers come and go as you scale and redeploy. The Public API tells your game clients and backend services where to connect right now, and webhooks tell you the moment anything changes.

How it works

Four steps

Create an access key

In the dashboard, create an access key and attach it to your deployment. You receive a key and a secret.

Sign the request

Build the string key:timestamp:nonce:path and sign it with your secret using HMAC-SHA256.

Call the endpoint

Send a POST with four headers: X-MC-Key, X-MC-Timestamp, X-MC-Nonce and X-MC-Signature.

Connect

Receive the current address, port, transport and health of your servers.

Endpoints

Server deployments

Every endpoint is a POST to https://api.multiconnectcloud.com.

EndpointReturns
/api/PublicNew/ServerDeployments/GetConnectionThe one server a client should connect to: the master in master-worker mode, or the combined server. Optionally in a preferred region.
/api/PublicNew/ServerDeployments/GetCombinedServerInfoAll combined servers, by region and build version.
/api/PublicNew/ServerDeployments/GetMasterServerInfoAll master servers, by region and build version.
/api/PublicNew/ServerDeployments/GetWorkerServerInfoAll worker servers, optionally only those reporting to one master region.
/api/PublicNew/ServerDeployments/ReleaseRetiringContainersEnds the drain period early for old servers you know are empty, which stops their charges sooner.

Security

Signed, scoped and rate limited

HMAC-SHA256 signatures

Every request is signed with your secret. The secret itself is never sent.

Replay protection

Timestamps must be within 5 minutes of server time, and each nonce can be used only once.

Client-distributable keys

Mark a key as client-distributable to ship it inside a game build. It can only read connection details.

Rate limited

60 requests per minute per IP address.

Scoped to a deployment

A key works only for the deployments it is attached to. Up to 5 keys per deployment, so you can rotate them.

Signed webhooks

Be told when servers start, stop or scale instead of polling. Each webhook is signed so you can check it came from the platform.

Examples

Where should this client connect?

Python

import hmac, hashlib, uuid, datetime, requests

KEY = "your-access-key"
SECRET = "your-access-secret"
BASE = "https://api.multiconnectcloud.com"
PATH = "/api/PublicNew/ServerDeployments/GetConnection"

timestamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
nonce = uuid.uuid4().hex
payload = f"{KEY}:{timestamp}:{nonce}:{PATH}"
signature = hmac.new(SECRET.encode(), payload.encode(), hashlib.sha256).hexdigest()

response = requests.post(
    BASE + PATH,
    headers={
        "X-MC-Key": KEY,
        "X-MC-Timestamp": timestamp,
        "X-MC-Nonce": nonce,
        "X-MC-Signature": signature,
    },
    json={"deploymentId": "your-deployment-id"},
)
data = response.json()
if data["status"] and data["connection"]:
    c = data["connection"]
    print(f"Connect to {c['ip']}:{c['port']} over {c['transport']} in {c['region']}")
else:
    print(data["message"])

C# (.NET and Unity)

var key = "your-access-key";
var secret = "your-access-secret";
var path = "/api/PublicNew/ServerDeployments/GetConnection";
var timestamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ");
var nonce = Guid.NewGuid().ToString("N");

using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var signature = Convert.ToHexString(
    hmac.ComputeHash(Encoding.UTF8.GetBytes($"{key}:{timestamp}:{nonce}:{path}"))).ToLowerInvariant();

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.multiconnectcloud.com" + path)
{
    Content = JsonContent.Create(new { deploymentId = "your-deployment-id" })
};
request.Headers.Add("X-MC-Key", key);
request.Headers.Add("X-MC-Timestamp", timestamp);
request.Headers.Add("X-MC-Nonce", nonce);
request.Headers.Add("X-MC-Signature", signature);
var response = await httpClient.SendAsync(request);

Node.js: list all worker servers

const crypto = require('crypto');

const key = 'your-access-key';
const secret = 'your-access-secret';
const path = '/api/PublicNew/ServerDeployments/GetWorkerServerInfo';
const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
const nonce = crypto.randomUUID();
const signature = crypto.createHmac('sha256', secret)
  .update(`${key}:${timestamp}:${nonce}:${path}`)
  .digest('hex');

const response = await fetch('https://api.multiconnectcloud.com' + path, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-MC-Key': key,
    'X-MC-Timestamp': timestamp,
    'X-MC-Nonce': nonce,
    'X-MC-Signature': signature,
  },
  body: JSON.stringify({ deploymentId: 'your-deployment-id' }),
});
const data = await response.json();
for (const s of data.containers) {
  console.log(`${s.region} ${s.role} ${s.ip}:${s.port} healthy=${s.isHealthy}`);
}

Questions

Do I need the Public API if I use the MultiConnect SDK?

No. The SDK finds the right server for you. The Public API is for clients and services that do not use the SDK.

Can I ship an access key in my game?

Only a key marked client-distributable. It can read connection details and nothing else.

Where are the connection details for APIs, websites and databases?

In the dashboard. Those addresses change only when you change them, so they do not need a lookup.

What is the rate limit?

60 requests per minute per IP address.

Try it with 500 free credits

Create an account and you get 500 credits to deploy with. No credit card required. There is no free hosting tier; the credits are the trial.