Développeurs · API

API Plugin : lier un serveur de jeu

Branche un plugin de serveur (Minecraft, Rust, ARK…) sur une cagnotte KeepAlive pour afficher la progression en jeu et attribuer automatiquement les récompenses. API serveur→serveur, par polling : aucune URL entrante à exposer.

GET/api/plugin/campaignGET/api/plugin/donations

1. Authentification

Générer une clé

Dans ton dashboard : Cagnotte → onglet Modifier → « Plugin en jeu » → Générer une clé. La clé complète (ka_live_…) n’est affichée qu’une seule fois : copie-la et colle-la dans la config de ton plugin.

Une clé est scopée à une seule cagnotte / un seul serveur.
Seule l’empreinte SHA-256 est stockée : personne ne peut relire ta clé. Perdue = régénère-en une.
Tu peux révoquer une clé à tout moment ; elle cesse aussitôt de fonctionner.

Utiliser la clé

Envoie la clé dans l’en-tête Authorization de chaque requête :

header

Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx

Sécurité : la clé est un secret serveur. Ne la mets jamais dans un client de jeu, un dépôt public, ou quoi que ce soit d’accessible aux joueurs.

2. Généralités

Base URL	`https://keepalive.gg` · dev local `http://localhost:3100`
Format	JSON pour les requêtes et les réponses.
Limite de débit	~120 requêtes / minute par clé. Au-delà → `429`.
Polling	Un intervalle de 30 à 60 s suffit largement.

Les erreurs suivent une enveloppe standard : { "error": { "code", "message" } }

401Clé absente, invalide ou révoquée.
404La cagnotte n’existe plus.
429Trop de requêtes, réessaie dans un instant.

GET/api/plugin/campaign

Retourne la progression de la cagnotte liée à la clé, à appeler périodiquement pour rafraîchir l’affichage en jeu.

cURL

curl https://keepalive.gg/api/plugin/campaign \
  -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Réponse 200

{
  "campaign": {
    "slug": "skycraft-survie",
    "title": "SkyCraft Survie",
    "game": "minecraft",
    "status": "published",
    "goalKind": "monthly",
    "goalCents": 2000,
    "currency": "EUR",
    "raisedCents": 1450,
    "pct": 73,
    "supporters": 12,
    "rewards": [
      { "minCents": 500, "title": "Role", "description": "…" }
    ]
  }
}

goalCents / raisedCents sont en centimes · pct déjà borné à 0 à 100 · goalKind vaut monthly ou oneshot.

GET/api/plugin/donations

Liste les dons encaissés, du plus ancien au plus récent, pour attribuer les récompenses. Le curseur évite de re-télécharger les anciens dons.

Param	Défaut	Description
`after`	aucun	Curseur opaque : le `nextCursor` de la page précédente. Omets-le au premier appel.
`limit`	50	Nombre max de dons (plafonné à 50).

cURL

curl "https://keepalive.gg/api/plugin/donations?after=CURSOR" \
  -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Réponse 200

{
  "donations": [
    {
      "id": "don_9f2c…",
      "donorName": "Nova",
      "amountCents": 1000,
      "currency": "EUR",
      "message": "gg",
      "recurring": false,
      "rewardTitle": "Kit VIP",
      "createdAt": "2026-07-21T18:04:11.000Z"
    }
  ],
  "nextCursor": "2026-07-21T18:04:11.000Z|don_9f2c…"
}

Champs exposés (publics uniquement) :

Champ	Description
`id`	Identifiant unique du don (sert à dé-dupliquer).
`donorName`	Nom public saisi par le donateur (`null` si anonyme).
`amountCents`	Montant du don, en centimes.
`message`	Message public du donateur (`null` si aucun).
`recurring`	`true` si c’est un don mensuel.
`rewardTitle`	Palier débloqué à donner en jeu (`null` si aucun).
`createdAt`	Date ISO 8601.

Jamais d’e-mail, d’identifiant Stripe ni de montant net : uniquement ce qui est déjà public sur la page de la cagnotte.

Boucle de polling recommandée

pseudo-code

curseur = charger_curseur()          # vide au premier lancement
ids_traités = charger_ids()          # anti-doublon

répéter toutes les 30 à 60 s :
  page = GET /api/plugin/donations?after=curseur
  pour chaque don dans page.donations :
    si don.id déjà traité : continuer
    si don.rewardTitle et don.donorName :
      joueur = trouver_joueur(don.donorName)
      si joueur : donner_récompense(joueur, don.rewardTitle)
    marquer don.id traité
  si page.nextCursor :
    curseur = page.nextCursor ; sauvegarder(curseur)

Toujours dé-dupliquer sur id : ne donne jamais deux fois la même récompense, même à la frontière du curseur.

3. Attribuer la récompense au bon joueur

KeepAlive ne connaît pas le compte en jeu du donateur, seulement le nom public qu’il a saisi (donorName). La convention recommandée :

Invite tes joueurs à donner en utilisant leur pseudo en jeu comme nom public.

Ton plugin fait alors correspondre donorName au joueur (insensible à la casse). Si personne ne correspond au moment du don, garde la récompense en attente et rejoue l’attribution à sa reconnexion.

Évolution prévue : un flux « code à réclamer » (/claim <code> en jeu) rendra l’attribution 100 % fiable, indépendamment du pseudo.

Prêt à brancher ton serveur ?

Génère une clé API depuis le dashboard de ta cagnotte et suis les exemples ci-dessus.

Ouvrir mon dashboard →