REST API 레퍼런스

SDK는 이 HTTPS + JSON API를 감싼 얇은 클라이언트이므로, 어떤 엔진, 도구, 서버에서도 API를 직접 사용할 수 있습니다.

코드 주석과 API 이름은 SDK와 일치하도록 영어로 유지합니다.

이 페이지의 내용

기본 사항
헤더
응답
예제
엔드포인트
프로젝트
플레이어 인증
리더보드
원격 구성
클라우드 저장
보상과 지갑

기본 사항#

Base URL: https://majacloud.majanite.com/v1. localhost를 제외하고는 HTTPS가 필수입니다. 요청 본문은 Content-Type: application/json인 JSON입니다.

클라이언트를 생성하거나 Postman, Insomnia로 가져오려면 OpenAPI 3.1 명세를 다운로드하세요.

헤더#

헤더	의미
`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도 있습니다:

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" }
  }
}

예제#

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
}

GET/auth/link/status로그인 플로우 상태 폴링클라이언트 키

쿼리

flow_id — uuid
flow_token — …

응답 200

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

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/configRSA로 서명된 라이브 구성. 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": "…"
        }
    ]
}