MAJACLOUD

Référence de l'API REST

Les SDK sont de simples clients au-dessus de cette API HTTPS + JSON : n'importe quel moteur, outil ou serveur peut donc l'utiliser directement.

Les commentaires du code et les noms d'API restent en anglais pour correspondre aux SDK.

Sur cette page

Principes de base#

URL de base : https://majacloud.majanite.com/v1. HTTPS est obligatoire, sauf depuis localhost. Les corps de requête sont en JSON avec Content-Type: application/json.

Téléchargez la description OpenAPI 3.1 pour générer des clients ou l'importer dans Postman ou Insomnia.

En-têtes#

En-têteSignification
X-Project-IDID du projet, indiqué dans le tableau de bord (toujours).
X-Client-KeyClé client publique (toujours ; peut être incluse sans risque dans les builds).
X-Secret-KeyClé secrète serveur, à la place de la clé client (uniquement de serveur à serveur).
AuthorizationBearer <access_token> pour les endpoints joueur.
X-Device-IDID d'installation facultatif (utilisé comme libellé d'appareil de l'invité).
X-Majacloud-SDKClient et version facultatifs, par ex. unity/2.0.0.

Réponses#

Chaque réponse est un objet JSON contenant ok. Les erreurs comportent aussi un code stable, un message, le request_id et parfois 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 + ")");
}

Exemple#

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#

Projet#

GET/projectInfos du projet, offre et clé publique de la configuration à distanceClé client
Réponse 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
        }
    }
}

Authentification joueur#

POST/auth/guestCréer un joueur invité et une sessionClé client
Corps
{
    "device_id": "optional installation id"
}
Réponse 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/refreshRenouveler le jeton de rafraîchissement et obtenir un nouveau jeton d'accèsClé client
Corps
{
    "refresh_token": "…"
}
Réponse 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
    }
}
Erreurs
  • unauthorized (reason: invalid | expired | revoked | reused)
POST/auth/logoutRévoquer la sessionClé client
Corps
{
    "refresh_token": "optional"
}
Réponse 200
{
    "ok": true,
    "revoked": true
}
POST/auth/link/startDémarrer la connexion web (lier un invité à un e-mail ou à Google)Jeton joueur
Corps
{
    "code_challenge": "base64url(sha256(verifier))",
    "code_challenge_method": "S256",
    "return_url": "optional, https on this host or an allowlisted scheme"
}
Réponse 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Échanger un flux terminé contre une sessionClé client
Corps
{
    "flow_id": "uuid",
    "exchange_code": "…",
    "code_verifier": "the original verifier"
}
Réponse 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/meLe joueur connectéJeton joueur
Réponse 200
{
    "ok": true,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}
PATCH/players/meModifier le nom affichéJeton joueur
Corps
{
    "display_name": "Nova"
}
Réponse 200
{
    "ok": true,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}
GET/players/{player_id}Lire n'importe quel joueur (clé secrète)Clé secrète
Réponse 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
            }
        ]
    }
}

Classements#

POST/leaderboards/{slug}/scoresEnvoyer un scoreJeton joueur
Corps
{
    "score": 120
}
Réponse 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"
    }
}
Erreurs
  • validation (bounds)
  • rate_limited (cooldown)
  • plan_limit (entry cap)
GET/leaderboards/{slug}/entriesMeilleures entréesClé client
Paramètres de requête
  • limit — 1-100 (default 10)
  • offset — 0+
  • period — current | previous
Réponse 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}/meMon rang et mon scoreJeton joueur
Paramètres de requête
  • period — current | previous
Réponse 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-meEntrées autour de mon rangJeton joueur
Paramètres de requête
  • radius — 1-25 (default 3)
Réponse 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
}

Configuration à distance#

GET/configConfiguration en direct, signée RSA ; envoyez If-None-Match pour obtenir 304Clé client
Réponse 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"
        }
    ]
}

Sauvegarde cloud#

GET/cloudLister les clés sauvegardéesJeton joueur
Réponse 200
{
    "ok": true,
    "keys": [
        {
            "key": "progress",
            "revision": 3,
            "size_bytes": 180,
            "updated_at": "…"
        }
    ],
    "total_bytes": 180
}
GET/cloud/{key}Charger un documentJeton joueur
Réponse 200
{
    "ok": true,
    "key": "progress",
    "data": {
        "level": 3
    },
    "revision": 3,
    "size_bytes": 180,
    "updated_at": "…"
}
PUT/cloud/{key}Sauvegarder un document (révision attendue facultative)Jeton joueur
Corps
{
    "data": {
        "level": 4
    },
    "revision": "optional: expected current revision (0 = create only)"
}
Réponse 200
{
    "ok": true,
    "key": "progress",
    "revision": 4,
    "size_bytes": 190,
    "updated_at": "…",
    "created": false
}
Erreurs
  • revision_mismatch (details.current_revision)
  • plan_limit (storage)
DELETE/cloud/{key}Supprimer un documentJeton joueur
Réponse 200
{
    "ok": true,
    "key": "progress",
    "deleted": true
}

Récompenses et portefeuille#

GET/rewardsRécompenses actives (indicateurs claimable avec un jeton joueur)Clé client
Réponse 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/claimRéclamer une récompenseJeton joueur
Corps
{
    "reward_key": "daily_coins"
}
Réponse 200
{
    "ok": true,
    "accepted": true,
    "reward_key": "daily_coins",
    "amount": 50,
    "currency": "coins",
    "balance": 150,
    "next_claim_at": "2026-10-10T00:00:00Z"
}
Erreurs
  • conflict (already claimed; details.next_claim_at)
GET/walletSoldes du portefeuilleJeton joueur
Réponse 200
{
    "ok": true,
    "wallets": [
        {
            "currency": "coins",
            "balance": 150,
            "updated_at": "…"
        }
    ]
}

Recherche dans les titres de page, les intertitres et le texte.

↑↓ pour naviguer ↵ pour ouvrir Esc pour fermer