REST API reference

The SDKs are thin clients over this HTTPS + JSON API, so any engine, tool or server can use it directly.

On this page

Basics
Headers
Responses
Example
Endpoints
Project
Player auth
Leaderboards
Remote config
Cloud save
Rewards and wallet

Basics#

Base URL: https://majacloud.majanite.com/v1. HTTPS is required except from localhost. Request bodies are JSON with Content-Type: application/json.

Download the OpenAPI 3.1 description to generate clients or import into Postman or Insomnia.

Headers#

Header	Meaning
`X-Project-ID`	Project ID from the dashboard (always).
`X-Client-Key`	Public client key (always, safe to ship in builds).
`X-Secret-Key`	Server secret key instead of the client key (server-to-server only).
`Authorization`	Bearer <access_token> for player endpoints.
`X-Device-ID`	Optional installation ID (used as the guest's device label).
`X-Majacloud-SDK`	Optional client and version, e.g. unity/2.0.0.

Responses#

Every response is JSON with ok. Errors also carry a stable code, a message, the request_id and sometimes details:

var top = await Majacloud.Leaderboards.GetTopAsync("coins", 10);
if (top.Ok)
{
    foreach (var entry in top.Value.Entries)
        Debug.Log($"#{entry.Rank} {entry.PlayerName} {entry.Score}");
}
else if (top.Error.IsRetryable)
{
    // Network, timeout, 5xx or rate limit: try again later
    Debug.Log("Retry in " + top.Error.RetryAfterSeconds + " s");
}
else
{
    Debug.LogWarning(top.Error.Code + ": " + top.Error.Message + " (" + top.Error.RequestId + ")");
}

GDScript

var top := await Majacloud.leaderboards.get_top("coins", 10)
if top.ok:
	for entry in top.value.entries:
		print("#%d %s %d" % [entry.rank, entry.player_name, entry.score])
elif top.is_retryable():
	# Network, timeout, 5xx or rate limit: try again later
	print("Retry in ", top.retry_after, " s")
else:
	push_warning("%s: %s (%s)" % [top.error, top.message, top.request_id])

JavaScript

const top = await mc.leaderboards.getTop('coins', { limit: 10 });
if (top.ok) {
  for (const entry of top.value.entries) {
    console.log(`#${entry.rank} ${entry.player_name} ${entry.score}`);
  }
} else if (top.error.retryable) {
  // Network, timeout, 5xx or rate limit: try again later
  console.log('Retry in', top.error.retryAfter, 's');
} else {
  console.warn(`${top.error.code}: ${top.error.message} (${top.error.requestId})`);
}

JSON

// Success
{ "ok": true, "entries": [ … ], "total": 42 }

// Error (HTTP 4xx/5xx)
{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Project rate limit reached. Try again in a minute.",
    "request_id": "6f1c2a9e-…",
    "details": { "limit": 120, "window": "minute" }
  }
}

Example#

bash

export PROJECT_ID="<project id>" CLIENT_KEY="pk_live_…"

curl https://majacloud.majanite.com/v1/project -H "X-Project-ID: $PROJECT_ID" -H "X-Client-Key: $CLIENT_KEY"

curl -X POST https://majacloud.majanite.com/v1/auth/guest -H "X-Project-ID: $PROJECT_ID" -H "X-Client-Key: $CLIENT_KEY" \
  -H "Content-Type: application/json" -d '{}'

Endpoints#

Project#

GET/projectProject info, plan and the Remote Config public keyClient key

Response 200

{
    "ok": true,
    "project": {
        "id": "8f3c…",
        "name": "Space Runner",
        "plan": "free",
        "config_version": 12,
        "config_public_key_xml": "<RSAKeyValue>…</RSAKeyValue>",
        "config_public_key_pem": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----\n",
        "services": {
            "player_auth": true,
            "leaderboards": true,
            "remote_config": true,
            "cloud_save": true,
            "rewards": true
        }
    }
}

Player auth#

POST/auth/guestCreate a guest player and a sessionClient key

Body

{
    "device_id": "optional installation id"
}

Response 201

{
    "ok": true,
    "auth_method": "guest",
    "access_token": "eyJ2IjoyLCJ0IjoiYWNjZXNz…",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "2d0f…",
    "refresh_expires_in": 2592000,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}

POST/auth/refreshRotate the refresh token and get a new access tokenClient key

Body

{
    "refresh_token": "…"
}

Response 200

{
    "ok": true,
    "auth_method": "guest",
    "access_token": "eyJ2IjoyLCJ0IjoiYWNjZXNz…",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "2d0f…",
    "refresh_expires_in": 2592000,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}

Errors

unauthorized (reason: invalid | expired | revoked | reused)

POST/auth/logoutRevoke the sessionClient key

Body

{
    "refresh_token": "optional"
}

Response 200

{
    "ok": true,
    "revoked": true
}

POST/auth/link/startStart the web sign-in (link a guest to email or Google)Player token

Body

{
    "code_challenge": "base64url(sha256(verifier))",
    "code_challenge_method": "S256",
    "return_url": "optional, https on this host or an allowlisted scheme"
}

Response 201

{
    "ok": true,
    "flow_id": "uuid",
    "flow_token": "…",
    "auth_url": "https://majacloud.majanite.com/player-auth.php?flow_id=…&flow_token=…",
    "expires_at": "2026-10-09T08:27:00Z",
    "poll_interval_seconds": 3
}

GET/auth/link/statusPoll the sign-in flowClient key

Query

flow_id — uuid
flow_token — …

Response 200

{
    "ok": true,
    "status": "pending | completed | consumed | expired",
    "exchange_code": "(only when completed)",
    "expires_at": "…"
}

POST/auth/link/exchangeExchange a completed flow for a sessionClient key

Body

{
    "flow_id": "uuid",
    "exchange_code": "…",
    "code_verifier": "the original verifier"
}

Response 200

{
    "ok": true,
    "auth_method": "guest",
    "access_token": "eyJ2IjoyLCJ0IjoiYWNjZXNz…",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "2d0f…",
    "refresh_expires_in": 2592000,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    },
    "merged_guest": true
}

GET/players/meThe signed-in playerPlayer token

Response 200

{
    "ok": true,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}

PATCH/players/meChange the display namePlayer token

Body

{
    "display_name": "Nova"
}

Response 200

{
    "ok": true,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}

GET/players/{player_id}Read any player (secret key)Secret key

Response 200

{
    "ok": true,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false,
        "email": "nova@example.com",
        "wallets": [
            {
                "currency": "coins",
                "balance": 150
            }
        ]
    }
}

Leaderboards#

POST/leaderboards/{slug}/scoresSubmit a scorePlayer token

Body

{
    "score": 120
}

Response 200

{
    "ok": true,
    "accepted": true,
    "entry": {
        "rank": 1,
        "player_id": "player_3f9c…",
        "player_name": "Nova",
        "score": 9840,
        "score_updated_at": "2026-10-09T08:12:00Z",
        "is_me": false
    },
    "period": {
        "key": "2026-W41",
        "ends_at": "2026-10-12T00:00:00Z"
    }
}

Errors

validation (bounds)
rate_limited (cooldown)
plan_limit (entry cap)

GET/leaderboards/{slug}/entriesTop entriesClient key

Query

limit — 1-100 (default 10)
offset — 0+
period — current | previous

Response 200

{
    "ok": true,
    "leaderboard": {
        "slug": "coins",
        "name": "Coins",
        "sort_type": "DESC",
        "score_mode": "BEST",
        "reset_rule": "WEEKLY"
    },
    "period": {
        "key": "2026-W41",
        "ends_at": "2026-10-12T00:00:00Z"
    },
    "entries": [
        {
            "rank": 1,
            "player_id": "player_3f9c…",
            "player_name": "Nova",
            "score": 9840,
            "score_updated_at": "2026-10-09T08:12:00Z",
            "is_me": false
        }
    ],
    "total": 42,
    "limit": 10,
    "offset": 0,
    "max_entries": 10
}

GET/leaderboards/{slug}/meMy rank and scorePlayer token

Query

period — current | previous

Response 200

{
    "ok": true,
    "entry": {
        "rank": 1,
        "player_id": "player_3f9c…",
        "player_name": "Nova",
        "score": 9840,
        "score_updated_at": "2026-10-09T08:12:00Z",
        "is_me": false
    },
    "total": 42
}

GET/leaderboards/{slug}/around-meEntries around my rankPlayer token

Query

radius — 1-25 (default 3)

Response 200

{
    "ok": true,
    "entries": [
        {
            "rank": 1,
            "player_id": "player_3f9c…",
            "player_name": "Nova",
            "score": 9840,
            "score_updated_at": "2026-10-09T08:12:00Z",
            "is_me": false
        }
    ],
    "me": {
        "rank": 1,
        "player_id": "player_3f9c…",
        "player_name": "Nova",
        "score": 9840,
        "score_updated_at": "2026-10-09T08:12:00Z",
        "is_me": false
    },
    "total": 42
}

Remote config#

GET/configLive config, RSA-signed; send If-None-Match to get 304Client key

Response 200

{
    "ok": true,
    "project_id": "8f3c…",
    "version": 12,
    "checksum": "sha256 of data",
    "data": "base64url(JSON payload)",
    "signature": "base64 RSA-SHA256 over data",
    "signature_algorithm": "rsa-sha256",
    "signing_key_id": "config-v1",
    "configs": [
        {
            "key": "enemy_damage",
            "type": "number",
            "value": "25"
        }
    ]
}

Cloud save#

GET/cloudList saved keysPlayer token

Response 200

{
    "ok": true,
    "keys": [
        {
            "key": "progress",
            "revision": 3,
            "size_bytes": 180,
            "updated_at": "…"
        }
    ],
    "total_bytes": 180
}

GET/cloud/{key}Load a documentPlayer token

Response 200

{
    "ok": true,
    "key": "progress",
    "data": {
        "level": 3
    },
    "revision": 3,
    "size_bytes": 180,
    "updated_at": "…"
}

PUT/cloud/{key}Save a document (optional expected revision)Player token

Body

{
    "data": {
        "level": 4
    },
    "revision": "optional: expected current revision (0 = create only)"
}

Response 200

{
    "ok": true,
    "key": "progress",
    "revision": 4,
    "size_bytes": 190,
    "updated_at": "…",
    "created": false
}

Errors

revision_mismatch (details.current_revision)
plan_limit (storage)

DELETE/cloud/{key}Delete a documentPlayer token

Response 200

{
    "ok": true,
    "key": "progress",
    "deleted": true
}

Rewards and wallet#

GET/rewardsActive rewards (claimable flags with a player token)Client key

Response 200

{
    "ok": true,
    "rewards": [
        {
            "reward_key": "daily_coins",
            "name": "Daily coins",
            "amount": 50,
            "currency": "coins",
            "cooldown": "daily",
            "claimable": true,
            "next_claim_at": null
        }
    ]
}

POST/rewards/claimClaim a rewardPlayer token

Body

{
    "reward_key": "daily_coins"
}

Response 200

{
    "ok": true,
    "accepted": true,
    "reward_key": "daily_coins",
    "amount": 50,
    "currency": "coins",
    "balance": 150,
    "next_claim_at": "2026-10-10T00:00:00Z"
}

Errors

conflict (already claimed; details.next_claim_at)

GET/walletWallet balancesPlayer token

Response 200

{
    "ok": true,
    "wallets": [
        {
            "currency": "coins",
            "balance": 150,
            "updated_at": "…"
        }
    ]
}