Aller au contenu principal

Créer et suspendre un MSP par l'API

Ce que fait ce parcours​

Un revendeur vend BaaStide dans son propre produit. Son produit crée un MSP par client, enrôle les machines, lance les sauvegardes et suspend un MSP quand le client arrête de payer. Aucune personne n'ouvre le portail.

Ce parcours utilise deux clés :

Clé de provisionnementClé API du MSP
Début de la clébst_prov_bst_msp_
Qui la détientLe revendeur. Une seule clé pour tous ses MSP.Un seul MSP.
Qui la créeL'équipe de la plateforme.La clé de provisionnement, à la création du MSP ou plus tard.
Ce qu'elle faitCrée un MSP, liste ses MSP, les suspend et les réactive, gère leurs clés API.Appelle l'API de son MSP : clients, machines, sauvegardes, politiques, restaurations, alertes, jetons d'enrôlement, journal d'audit.
ExpirationAucune par défaut.365 jours par défaut, 730 jours au plus.
RenouvellementNon.Oui : deux clés vivantes par MSP.

Cette page donne les étapes dans l'ordre. Chaque étape nomme la clé et la portée nécessaires.

Prérequis​

  • Une clé de provisionnement. Voir Clés de provisionnement.
  • L'adresse du portail qui vous sert, par exemple https://portail.example.com/api.
  • Un coffre à secrets pour garder les clés API des MSP.
  • Les règles communes des appels. Voir Appeler l'API REST.

1. Créer un MSP​

  1. Appelez POST /provisioning/msps avec la clé de provisionnement.
  2. Dans le corps, donnez name : le nom du MSP, de 1 à 100 caractères.
  3. Ajoutez api_key si vous voulez choisir le nom, les portées, l'expiration ou les adresses de la première clé API.
  4. Lisez la réponse. Le champ msp donne l'identifiant du MSP. Le champ api_key décrit sa première clé API. Le champ secret donne la clé elle-même.
  5. Enregistrez secret dans votre coffre à secrets.
POST /api/provisioning/msps HTTP/1.1
Authorization: Bearer bst_prov_...
Content-Type: application/json

{"name": "Acme IT", "api_key": {"name": "integration-acme"}}

Le champ secret est affiché dans cette réponse seulement. BaaStide ne le garde pas en clair.

Sans champ api_key, la première clé prend le nom provisioning, les portées read, operate et browse, et une expiration de un an.

Le nouveau MSP n'a aucun utilisateur. BaaStide n'envoie aucune invitation et aucun email. Ses sauvegardes vont vers le stockage par défaut de la plateforme.

Dans les étapes suivantes, la clé API du MSP remplace la clé de provisionnement.

2. Vérifier la clé API du MSP​

  1. Appelez GET /msp avec la clé API du MSP. Cette route demande la portée read.
  2. Lisez la réponse : elle donne id, name et status.

Un status égal à active confirme que la clé fonctionne.

3. Créer un client​

Un client est l'entreprise dont vous sauvegardez les machines.

  1. Appelez POST /clients avec la clé API du MSP. Cette route demande la portée operate.
  2. Dans le corps, donnez name : le nom du client.
  3. Lisez le champ id de la réponse : c'est l'identifiant du client.

Voir Clients pour la même action dans le portail.

4. Enrôler une machine​

  1. Appelez POST /enrollment-tokens avec la portée operate. Dans le corps, donnez client_id.
  2. Lisez la réponse. Le champ token est le jeton. Le champ install_command donne la commande d'installation Linux. Le champ install_command_windows donne la commande PowerShell.
  3. Lancez install_command en tant que root sur la machine Linux, ou install_command_windows dans une console PowerShell élevée sur la machine Windows.
  4. Appelez GET /enrollment-tokens?client_id=<identifiant du client> et cherchez votre jeton dans items. Quand son champ used_by_endpoint_id est rempli, la machine est enrôlée. Cet identifiant est celui de l'endpoint.
  5. Appelez GET /endpoints/{id}/agent jusqu'à un status égal à online.

Un jeton d'enrôlement est à usage unique. Il vit 7 jours. Voir Créer un jeton d'enrôlement.

Pour beaucoup de machines, utilisez un jeton de déploiement. Voir Déployer sur beaucoup de machines.

5. Créer une politique de sauvegarde​

Une machine enrôlée n'a aucune politique. Elle ne sauvegarde rien avant d'en recevoir une.

  1. Appelez POST /endpoints/{id}/policies avec la portée operate.
  2. Dans le corps, donnez name, enabled, dataset, schedules, timezone et retention.
  3. Dans dataset, donnez type égal à files, et paths : au moins un dossier à sauvegarder.
  4. Lisez le champ id de la réponse : c'est l'identifiant de la politique.
POST /api/endpoints/<id>/policies HTTP/1.1
Authorization: Bearer bst_msp_...
Content-Type: application/json

{"name": "Fichiers", "enabled": true,
 "dataset": {"type": "files", "paths": ["/etc"], "excludes": [], "exclude_caches": true, "one_file_system": false},
 "schedules": [{"frequency": "daily", "start_at": "2026-01-05T00:00:00Z", "times": ["22:00"]}],
 "timezone": "Europe/Paris", "retention": {"keep_daily": 7}}

Pour modifier une politique existante, appelez PUT /endpoints/{id}/policies/{policyId} avec la portée operate. Voir Politique de sauvegarde de fichiers.

6. Lancer une sauvegarde​

  1. Appelez POST /endpoints/{id}/jobs avec la portée operate et le corps {"type": "backup"}.
  2. Lisez le champ id de la réponse : c'est l'identifiant de la tâche.
  3. Appelez GET /jobs/{id} avec la portée read, jusqu'à un état final : succeeded, partial, failed, cancelled, interrupted ou missed.
  4. Sur un succès, lisez le champ snapshot_id : c'est le nouveau point de restauration.

Sans politique de sauvegarde de fichiers, ou avec une politique sans chemin, l'appel reçoit 409 no_file_policy. Aucune tâche n'est créée. Faites l'étape 5 d'abord.

Juste après l'enrôlement, la réponse peut être 409 repo_not_ready pendant quelques secondes. La plateforme prépare le dépôt. Réessayez.

7. Parcourir un point de restauration​

  1. Appelez POST /endpoints/{id}/snapshots/{snapshot_id}/tree avec la portée browse et le corps {"path": "/"}.
  2. Lisez le tableau entries. Chaque entrée donne name et type. Le champ size est donné pour un fichier seulement. Le champ mtime est facultatif.
  3. Pour la page suivante, rappelez la route avec le champ cursor égal au next_cursor reçu.
  4. Pour descendre d'un niveau, rappelez la route avec le chemin du dossier.

Pour chercher un fichier par son nom, appelez POST /endpoints/{id}/snapshots/{snapshot_id}/search.

8. Restaurer un fichier​

  1. Appelez POST /endpoints/{id}/restores avec la portée operate.
  2. Donnez snapshot_id, paths (de 1 à 1000 chemins) et target.
  3. Pour écrire dans un nouveau dossier, utilisez "target": {"mode": "directory", "path": "<dossier>"}. Pour écrire les fichiers à leur place d'origine, utilisez "target": {"mode": "original"}.
  4. Lisez le champ restore_session_id de la réponse.
  5. Appelez GET /restore-sessions/{id} avec la portée read, jusqu'à un état succeeded, partial, failed ou cancelled.
POST /api/endpoints/<id>/restores HTTP/1.1
Authorization: Bearer bst_msp_...
Content-Type: application/json

{"snapshot_id": "...", "paths": ["/etc/hostname"], "target": {"mode": "directory", "path": "/tmp/restauration-1"}}

Sans champ overwrite, BaaStide n'écrase aucun fichier existant.

Le mode original écrit sur la machine d'origine, ou sur une autre machine du même client avec le même système. Pour une autre machine, ajoutez target_endpoint_id.

  • Une autre machine du même client avec un autre système reçoit 409 original_not_allowed.
  • Une machine d'un autre client reçoit 403 forbidden : une clé API ne restaure jamais vers un autre client.
  • Un fichier d'un partage réseau revient à sa place d'origine sur la machine d'origine seulement. Sur une autre machine, restaurez dans un dossier.

Voir Restaurer des fichiers depuis le portail pour la même action dans le portail.

9. Suspendre un MSP​

Suspendez un MSP quand votre client arrête de payer.

  1. Appelez POST /provisioning/msps/{id}/suspend avec la clé de provisionnement.
  2. N'envoyez aucun en-tête Content-Type, ou envoyez le corps {}.
  3. Lisez la réponse : le champ status vaut suspended.

Après la suspension :

  • Les clés API du MSP reçoivent 403 msp_suspended sur toutes les routes, sauf GET /msp.
  • Aucune nouvelle sauvegarde ne démarre. Les sauvegardes déjà planifiées sont annulées, et le planificateur n'en crée plus. Aucune alerte n'est envoyée pour ces annulations.
  • Une sauvegarde en cours au moment de la suspension se termine normalement.
  • Rien n'est supprimé : les points de restauration, les clés, les politiques et les clients restent.

Un deuxième appel sur un MSP déjà suspendu ne change rien et répond 200.

10. Réactiver un MSP​

  1. Appelez POST /provisioning/msps/{id}/reactivate avec la clé de provisionnement.
  2. Lisez la réponse : le champ status vaut active.

Les politiques sont planifiées à partir de la réactivation. Les sauvegardes de la période de suspension ne sont pas rattrapées.

Un deuxième appel sur un MSP déjà actif ne change rien et répond 200.

11. Renouveler la clé API d'un MSP​

Renouvelez une clé avant son expiration, ou quand vous pensez qu'elle a fuité.

  1. Appelez GET /provisioning/msps/{id}/api-keys avec la clé de provisionnement. Lisez last_used_at et last_used_ip de chaque clé.
  2. Appelez POST /provisioning/msps/{id}/api-keys/{key_id}/rotate. La nouvelle clé garde le nom, les portées et les adresses de l'ancienne.
  3. Enregistrez le champ secret de la réponse dans votre coffre à secrets, puis mettez la nouvelle clé dans votre produit. Les deux clés fonctionnent en même temps.
  4. Vérifiez que l'ancienne clé n'est plus utilisée : son champ last_used_at n'avance plus.
  5. Appelez DELETE /provisioning/msps/{id}/api-keys/{ancien_key_id}.

Un MSP a au plus deux clés vivantes. Une troisième création reçoit 409 api_key_limit : révoquez d'abord une clé.

Une révocation agit tout de suite, sur tous les serveurs. Vous ne pouvez pas l'annuler.

Limites et précautions​

  • Testez une restauration après le premier enrôlement de chaque client. Une sauvegarde n'est utile que si la restauration marche. Voir Tester ses restaurations.
  • Une clé de provisionnement ne lit aucune donnée d'un MSP. Pour l'état du parc, utilisez la clé API du MSP.
  • Une clé de provisionnement ne supprime pas un MSP. Demandez-le à l'équipe de la plateforme.
  • Un MSP créé dans le portail ne peut pas être géré avec une clé de provisionnement. Il répond 404 not_found.
  • Une installation qui n'accepte qu'un seul MSP refuse la création d'un deuxième MSP, avec le code 409 msp_limit_reached.
  • Une suppression de client ou d'endpoint attend 72 heures. Une clé API ne raccourcit pas ce délai ; elle peut seulement annuler l'action. Voir Délai de 72 heures.
  • Gardez chaque clé API dans un coffre à secrets, et donnez une clé différente à chaque intégration. Le journal d'audit nomme la clé qui a agi. Voir Journal d'audit.

Référence​