MAJACLOUD

REST API 参考

各 SDK 都是基于这套 HTTPS + JSON API 的轻量客户端，因此任何引擎、工具或服务器都可以直接使用它。

代码注释和 API 名称保留英文，以便与 SDK 保持一致。

本页内容

基础#

基础 URL：https://majacloud.majanite.com/v1。除 localhost 外，必须使用 HTTPS。请求体为 JSON，并带有 Content-Type: application/json。

下载 OpenAPI 3.1 描述文件，用于生成客户端，或导入 Postman 或 Insomnia。

请求头#

请求头含义
X-Project-ID控制台中的项目 ID（始终需要）。
X-Client-Key公开的客户端密钥（始终需要，可以安全地打包进构建）。
X-Secret-Key服务器私密密钥，代替客户端密钥使用（仅限服务器之间）。
Authorization玩家端点使用 Bearer <access_token>。
X-Device-ID可选的安装 ID（用作游客的设备标签）。
X-Majacloud-SDK可选的客户端和版本，例如 unity/2.0.0。

响应#

每个响应都是带有 ok 的 JSON。错误还会包含稳定的 code、message、request_id，有时还有 details：

C#
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 + ")");
}

示例#

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 '{}'

端点#

项目#

GET/project项目信息、套餐和远程配置公钥客户端密钥
响应 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
        }
    }
}

玩家认证#

POST/auth/guest创建游客玩家和会话客户端密钥
请求体
{
    "device_id": "optional installation id"
}
响应 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/refresh轮换刷新令牌并获取新的访问令牌客户端密钥
请求体
{
    "refresh_token": "…"
}
响应 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
    }
}
错误
  • unauthorized (reason: invalid | expired | revoked | reused)
POST/auth/logout撤销会话客户端密钥
请求体
{
    "refresh_token": "optional"
}
响应 200
{
    "ok": true,
    "revoked": true
}
POST/auth/link/start开始网页登录（将游客关联到邮箱或 Google）玩家令牌
请求体
{
    "code_challenge": "base64url(sha256(verifier))",
    "code_challenge_method": "S256",
    "return_url": "optional, https on this host or an allowlisted scheme"
}
响应 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
}
POST/auth/link/exchange将已完成的流程兑换为会话客户端密钥
请求体
{
    "flow_id": "uuid",
    "exchange_code": "…",
    "code_verifier": "the original verifier"
}
响应 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/me当前登录的玩家玩家令牌
响应 200
{
    "ok": true,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}
PATCH/players/me修改显示名称玩家令牌
请求体
{
    "display_name": "Nova"
}
响应 200
{
    "ok": true,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}
GET/players/{player_id}读取任意玩家（私密密钥）私密密钥
响应 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
            }
        ]
    }
}

排行榜#

POST/leaderboards/{slug}/scores提交分数玩家令牌
请求体
{
    "score": 120
}
响应 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"
    }
}
错误
  • validation (bounds)
  • rate_limited (cooldown)
  • plan_limit (entry cap)
GET/leaderboards/{slug}/entries排名靠前的条目客户端密钥
查询参数
  • limit — 1-100 (default 10)
  • offset — 0+
  • period — current | previous
响应 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}/me我的排名和分数玩家令牌
查询参数
  • period — current | previous
响应 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-me我的排名附近的条目玩家令牌
查询参数
  • radius — 1-25 (default 3)
响应 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
}

远程配置#

GET/config实时配置，经 RSA 签名；发送 If-None-Match 可获得 304客户端密钥
响应 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"
        }
    ]
}

云存档#

GET/cloud列出已保存的键玩家令牌
响应 200
{
    "ok": true,
    "keys": [
        {
            "key": "progress",
            "revision": 3,
            "size_bytes": 180,
            "updated_at": "…"
        }
    ],
    "total_bytes": 180
}
GET/cloud/{key}加载文档玩家令牌
响应 200
{
    "ok": true,
    "key": "progress",
    "data": {
        "level": 3
    },
    "revision": 3,
    "size_bytes": 180,
    "updated_at": "…"
}
PUT/cloud/{key}保存文档（可选预期修订号）玩家令牌
请求体
{
    "data": {
        "level": 4
    },
    "revision": "optional: expected current revision (0 = create only)"
}
响应 200
{
    "ok": true,
    "key": "progress",
    "revision": 4,
    "size_bytes": 190,
    "updated_at": "…",
    "created": false
}
错误
  • revision_mismatch (details.current_revision)
  • plan_limit (storage)
DELETE/cloud/{key}删除文档玩家令牌
响应 200
{
    "ok": true,
    "key": "progress",
    "deleted": true
}

奖励和钱包#

GET/rewards已启用的奖励（带玩家令牌时包含可领取标记）客户端密钥
响应 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/claim领取奖励玩家令牌
请求体
{
    "reward_key": "daily_coins"
}
响应 200
{
    "ok": true,
    "accepted": true,
    "reward_key": "daily_coins",
    "amount": 50,
    "currency": "coins",
    "balance": 150,
    "next_claim_at": "2026-10-10T00:00:00Z"
}
错误
  • conflict (already claimed; details.next_claim_at)
GET/wallet钱包余额玩家令牌
响应 200
{
    "ok": true,
    "wallets": [
        {
            "currency": "coins",
            "balance": 150,
            "updated_at": "…"
        }
    ]
}

搜索页面标题、小标题和正文。

↑↓ 选择 ↵ 打开 Esc 关闭