{ "openapi": "3.0.3", "info": { "title": "MAJACLOUD Game API", "version": "2.0.0", "description": "Backend services for Unity games: player auth, leaderboards, remote config, cloud save and rewards. Every response is {\"ok\":true,...} or {\"ok\":false,\"error\":{\"code\",\"message\",\"details\"}}." }, "servers": [ { "url": "https://majacloud.majanite.com/v1" } ], "components": { "securitySchemes": { "ProjectId": { "type": "apiKey", "in": "header", "name": "X-Project-ID" }, "ClientKey": { "type": "apiKey", "in": "header", "name": "X-Client-Key" }, "SecretKey": { "type": "apiKey", "in": "header", "name": "X-Secret-Key" }, "PlayerToken": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "validation", "unauthorized", "forbidden", "plan_limit", "not_found", "method_not_allowed", "conflict", "revision_mismatch", "https_required", "rate_limited", "quota_exceeded", "server_error" ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object" } } } } } } }, "paths": { "/project": { "get": { "tags": [ "Project" ], "summary": "Project info, plan and the Remote Config public key", "security": [ { "ProjectId": [], "ClientKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "project": { "id": "8f3c…", "name": "Space Runner", "plan": "free", "config_version": 12, "config_public_key_xml": "…", "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 } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/guest": { "post": { "tags": [ "Player auth" ], "summary": "Create a guest player and a session", "security": [ { "ProjectId": [], "ClientKey": [] } ], "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "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 } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "device_id": "optional installation id" } } } } } }, "/auth/refresh": { "post": { "tags": [ "Player auth" ], "summary": "Rotate the refresh token and get a new access token", "security": [ { "ProjectId": [], "ClientKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "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 } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "refresh_token": "…" } } } } } }, "/auth/logout": { "post": { "tags": [ "Player auth" ], "summary": "Revoke the session (Bearer and/or refresh token)", "security": [ { "ProjectId": [], "ClientKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "revoked": true } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "refresh_token": "optional" } } } } } }, "/auth/link/start": { "post": { "tags": [ "Player auth" ], "summary": "Start the web sign-in (link a guest to an email/Google account)", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "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 } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "code_challenge": "base64url(sha256(verifier))", "code_challenge_method": "S256", "return_url": "optional, https on this host or an allowlisted scheme" } } } } } }, "/auth/link/status": { "get": { "tags": [ "Player auth" ], "summary": "Poll the sign-in flow", "security": [ { "ProjectId": [], "ClientKey": [] } ], "parameters": [ { "name": "flow_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "uuid" }, { "name": "flow_token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "…" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "status": "pending | completed | consumed | expired", "exchange_code": "(only when completed)", "expires_at": "…" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/link/exchange": { "post": { "tags": [ "Player auth" ], "summary": "Exchange a completed flow for a session", "security": [ { "ProjectId": [], "ClientKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "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 } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "flow_id": "uuid", "exchange_code": "…", "code_verifier": "the original verifier" } } } } } }, "/players/me": { "get": { "tags": [ "Player auth" ], "summary": "The signed-in player", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "player": { "id": "c7a1…", "player_id": "player_3f9c…", "display_name": "Guest 4821", "auth_type": "guest", "email_verified": false } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Player auth" ], "summary": "Change the display name", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "player": { "id": "c7a1…", "player_id": "player_3f9c…", "display_name": "Guest 4821", "auth_type": "guest", "email_verified": false } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "display_name": "Nova" } } } } } }, "/players/{player_id}": { "get": { "tags": [ "Player auth" ], "summary": "Read any player (server key)", "security": [ { "ProjectId": [], "SecretKey": [] } ], "parameters": [ { "name": "player_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "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 } ] } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leaderboards/{slug}/scores": { "post": { "tags": [ "Leaderboards" ], "summary": "Submit a score (name comes from the account)", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "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" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "score": 120 } } } } } }, "/leaderboards/{slug}/entries": { "get": { "tags": [ "Leaderboards" ], "summary": "Top entries", "security": [ { "ProjectId": [], "ClientKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1-100 (default 10)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "string" }, "description": "0+" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string" }, "description": "current | previous" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "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 } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leaderboards/{slug}/me": { "get": { "tags": [ "Leaderboards" ], "summary": "My rank and score", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string" }, "description": "current | previous" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "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 } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leaderboards/{slug}/around-me": { "get": { "tags": [ "Leaderboards" ], "summary": "Entries around my rank", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [ { "name": "radius", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1-25 (default 3)" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "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 } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/config": { "get": { "tags": [ "Remote config" ], "summary": "Live config, RSA-signed; send If-None-Match to get 304", "security": [ { "ProjectId": [], "ClientKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "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" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cloud": { "get": { "tags": [ "Cloud save" ], "summary": "List saved keys", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "keys": [ { "key": "progress", "revision": 3, "size_bytes": 180, "updated_at": "…" } ], "total_bytes": 180 } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cloud/{key}": { "get": { "tags": [ "Cloud save" ], "summary": "Load a document", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "key": "progress", "data": { "level": 3 }, "revision": 3, "size_bytes": 180, "updated_at": "…" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Cloud save" ], "summary": "Save a document (optional optimistic revision)", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "key": "progress", "revision": 4, "size_bytes": 190, "updated_at": "…", "created": false } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "data": { "level": 4 }, "revision": "optional: expected current revision (0 = create only)" } } } } }, "delete": { "tags": [ "Cloud save" ], "summary": "Delete a document", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "key": "progress", "deleted": true } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rewards": { "get": { "tags": [ "Rewards and wallet" ], "summary": "Active rewards (claimable flags with a Bearer token)", "security": [ { "ProjectId": [], "ClientKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "rewards": [ { "reward_key": "daily_coins", "name": "Daily coins", "amount": 50, "currency": "coins", "cooldown": "daily", "claimable": true, "next_claim_at": null } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rewards/claim": { "post": { "tags": [ "Rewards and wallet" ], "summary": "Claim a reward (server-authoritative)", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "accepted": true, "reward_key": "daily_coins", "amount": 50, "currency": "coins", "balance": 150, "next_claim_at": "2026-10-10T00:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "reward_key": "daily_coins" } } } } } }, "/wallet": { "get": { "tags": [ "Rewards and wallet" ], "summary": "Wallet balances", "security": [ { "ProjectId": [], "ClientKey": [], "PlayerToken": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true, "wallets": [ { "currency": "coins", "balance": 150, "updated_at": "…" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }