Aller au contenu

Créer et utiliser un jeton API à permissions fines

Les jetons API permettent à tes scripts, bots et jobs CI d'appeler l'API Zaroz Cloud sans conserver le mot de passe de ton compte ni ta session de navigateur. Chaque nouveau jeton refuse tout par défaut : tu choisis précisément ses actions et ses ressources.

La liste complète des endpoints, corps de requête et schémas de réponse se trouve dans la référence OpenAPI du Kernel.

Avant d'en créer un

Traite un jeton comme un mot de passe. Quiconque le récupère peut utiliser tous ses droits jusqu'à son expiration ou sa révocation.

  • Crée un jeton distinct pour chaque intégration.
  • N'accorde que les capacités indispensables.
  • Préfère une commande ou une fleet précise à toutes les ressources.
  • Ajoute une expiration dès que l'intégration sait renouveler son secret.
  • Ne place jamais un jeton dans du JavaScript frontend, une application mobile, un dépôt public ou un message au support.

Ton compte reste la limite

Un jeton n'a jamais plus de droits que son propriétaire à l'instant présent. Si une adhésion à une commande ou un rôle administrateur est retiré plus tard, le jeton perd immédiatement cet accès lui aussi.

Créer le jeton

  1. Ouvre le tableau de bord Zaroz Cloud.
  2. Va dans Paramètres → Sécurité → Jetons API.
  3. Sélectionne Créer un jeton.
  4. Donne-lui un nom parlant, comme minecraft-status-bot ou gitlab-production-deploy.
  5. Choisis éventuellement une date d'expiration.
  6. Ajoute les capacités nécessaires et une portée pour chacune.
  7. Vérifie le résumé et crée le jeton.
  8. Copie-le immédiatement dans ton gestionnaire de mots de passe ou coffre de secrets.

Le jeton en clair n'est affiché qu'une seule fois. Zaroz ne conserve qu'un hash irréversible ; le support ne peut donc pas le récupérer. Si tu le perds, révoque-le et crées-en un autre.

Un jeton doté de capacités administratives exige une session administrateur élevée. Les rôles actuels du propriétaire sont malgré tout revérifiés à chaque requête.

Comprendre les portées

Chaque autorisation associe une capacité exacte à une portée :

Portée Ce qu'elle autorise Bon usage
Une ressource Uniquement la commande ou l'objet sélectionné Bot d'état pour un serveur Minecraft
Arbre de ressources Une fleet et ses enfants Automatisation d'une fleet
Type de ressource Toutes les ressources d'un type auxquelles tu as accès Inventaire de toutes tes commandes
Globale La capacité sans limite de ressource Automatisation administrative ; à utiliser avec prudence

Les capacités n'acceptent aucun joker. Par exemple, orders.read n'inclut pas orders.server.toggle, et orders.server.toggle ne donne pas accès au terminal.

Authentifier une requête

Envoie le jeton dans l'en-tête Authorization :

Authorization: Bearer TON_JETON_API

L'URL de base est :

https://kernel.zaroz.cloud/api/v1

N'appelle pas directement l'API depuis un site public

Le code du navigateur est visible par chaque visiteur. Garde le jeton dans un serveur, un bot, un coffre CI ou un autre backend de confiance.

Exemple JavaScript : lire l'état d'une commande

Crée un jeton avec orders.read, limité à la commande voulue. Définis le jeton et l'ID comme variables d'environnement, puis lance cet exemple avec Node.js 18 ou plus récent :

status.mjs
const API_BASE = "https://kernel.zaroz.cloud/api/v1";
const token = process.env.ZAROZ_API_TOKEN;
const orderId = process.env.ZAROZ_ORDER_ID;

if (!token || !orderId) {
  throw new Error("Set ZAROZ_API_TOKEN and ZAROZ_ORDER_ID first");
}

async function zaroz(path, options = {}) {
  const response = await fetch(`${API_BASE}${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
      ...options.headers,
    },
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Zaroz API ${response.status}: ${body}`);
  }

  return response.json();
}

const status = await zaroz(`/orders/${orderId}/status`);
const primary = status.provisions.find((provision) => provision.is_primary);

console.log(`Order state: ${status.state}`);
console.log(`Primary service: ${primary?.status ?? "not provisioned"}`);

if (primary?.external_ip && primary?.external_port) {
  console.log(`Address: ${primary.external_ip}:${primary.external_port}`);
}

export ZAROZ_API_TOKEN='colle-le-jeton-ici'
export ZAROZ_ORDER_ID='00000000-0000-0000-0000-000000000000'
node status.mjs

Consulte Get Order Status dans la référence OpenAPI pour tous les états et champs possibles.

Erreurs à gérer

  • 401 Authentication required : jeton absent, mal formé, expiré ou révoqué.
  • 403 Resource access forbidden : le jeton, son propriétaire ou les deux n'ont pas le droit requis.
  • 404 Resource not found : l'ID est incorrect ou la ressource est volontairement masquée à cette identité.
  • 429 Rate limit exceeded : attends et réessaie avec un délai exponentiel.
  • 5xx : considère l'erreur comme temporaire, limite les tentatives et ne journalise jamais le jeton.

Renouveler ou révoquer un jeton

Crée d'abord son remplaçant, mets l'intégration à jour, vérifie-la, puis révoque l'ancien depuis Paramètres → Sécurité → Jetons API. Les jetons avec expiration déclenchent des rappels avant la date et une notification lorsqu'ils expirent.

Les actions apparaissent dans les journaux d'audit avec le propriétaire et l'identité du jeton. Des noms explicites rendent ces traces bien plus utiles pendant un incident.

Exemples suivants