Appeler l'API REST

Ce que fait l'API REST

L'API REST de BaaStide fait les mêmes actions que le portail, sans personne devant l'écran. Un intégrateur l'appelle depuis son produit : il crée des clients, enrôle des machines, lance des sauvegardes et des restaurations, et lit l'état du parc.

Un appel porte une clé API de MSP. Cette clé est la clé d'un service, pas celle d'une personne. Elle atteint un seul MSP. Un administrateur de la plateforme la crée.

Cette page décrit les règles communes à tous les appels : l'authentification, la pagination, les erreurs, les limites de débit et les adresses autorisées.

Prérequis

• Une clé API du MSP. Un administrateur de la plateforme la crée. Voir MSP et clés API.
• L'adresse du portail BaaStide qui vous sert.
• Un client HTTP qui envoie un en-tête Authorization et un corps JSON.

La page Rôles et droits décrit les portées d'une clé et ce qu'une clé ne fait jamais.

Lire le contrat de l'API

Le portail affiche le contrat de l'API de la version déployée.

1. Connectez-vous au portail.
2. Ouvrez le menu du compte, en haut à droite.
3. Cliquez sur API (Swagger).

La page liste chaque route, ses paramètres et ses réponses. Chaque route nomme la portée nécessaire (x-api-key-scope). Un bouton enregistre le contrat au format OpenAPI 3.1.

Cette page est une documentation. Elle n'envoie aucune requête à l'API.

Un utilisateur de MSP voit seulement les routes qu'une clé API de MSP peut appeler. Son bouton de téléchargement est Télécharger openapi-csp.json.

Un administrateur de la plateforme voit toutes les routes, les routes de la plateforme incluses. Son bouton de téléchargement est Télécharger openapi.json.

La section Référence donne les mêmes routes en français, dans le site.

Authentifier un appel

L'adresse de base est https://<portail>/api. Toutes les routes sont sous cette adresse.

1. Mettez la clé dans l'en-tête Authorization, sous la forme Bearer <clé>.
2. Pour une requête avec un corps, ajoutez l'en-tête Content-Type: application/json.
3. Envoyez la requête.

GET /api/msp HTTP/1.1
Host: portail.example.com
Authorization: Bearer bst_msp_...

Un appel n'envoie pas de cookie et pas d'en-tête de protection CSRF. Ce n'est pas un navigateur.

La route GET /msp donne le MSP de la clé : son identifiant, son nom et son état. Utilisez-la pour vérifier qu'une clé fonctionne.

Corps d'une requête

• Un corps est au format JSON. Un autre format reçoit 415 unsupported_media_type.
• Une route sans corps, par exemple POST /provisioning/msps/{id}/suspend, accepte deux formes : aucun en-tête Content-Type, ou le corps {}.
• L'en-tête Content-Type: application/json avec un corps vide reçoit 400 validation_failed.

Portées d'une clé

Chaque route demande une portée. Le contrat de l'API la donne pour chaque route.

Portée	Ce qu'elle permet
read	Toutes les lectures du MSP : clients, endpoints, tâches, politiques, alertes, journal d'audit, tableau de bord. Toujours présente dans une clé.
operate	Les écritures : clients, jetons d'enrôlement, sauvegardes, politiques, restaurations, alertes, tags, partages, Microsoft 365, suppressions.
browse	Le contenu d'un point de restauration ou d'une machine : les noms, les tailles et les dates des fichiers.
recovery	L'appairage d'un média de restauration bare metal. Jamais donnée par défaut.

Sans choix de portées, la clé reçoit read, operate et browse. Demandez la portée recovery à la création de la clé.

Donnez à chaque clé les portées dont elle a besoin, et pas plus. Un outil de supervision n'a besoin que de read. Une clé sans browse ne voit aucun nom de fichier de vos clients.

Un refus de portée donne 403 forbidden. Le champ message nomme la portée qui manque.

Lire une liste page par page

Les listes de l'API sont paginées. Elles donnent les entrées les plus récentes d'abord.

1. Appelez la route avec le paramètre limit. La valeur va de 1 à 100. Sans limit, l'API en donne 50.
2. Lisez le tableau items de la réponse.
3. Lisez le champ next_cursor.
4. Si next_cursor n'est pas null, rappelez la route avec cursor=<valeur de next_cursor>.
5. Répétez jusqu'à next_cursor égal à null.

GET /api/clients?limit=50 HTTP/1.1
Authorization: Bearer bst_msp_...

Le curseur est opaque. Ne le construisez pas vous-même : reprenez toujours la valeur donnée par next_cursor.

Trois listes ont leurs propres règles.

Route	Tableau	limit	Sans limit	Ordre
GET /jobs/{id}/logs	items	1 à 500	200	Les lignes les plus anciennes d'abord.
POST /endpoints/{id}/snapshots/{snapshot_id}/tree	entries	1 à 1000	500	Par nom.
POST /endpoints/{id}/snapshots/{snapshot_id}/search	entries	1 à 1000	200	En profondeur : le contenu d'un dossier vient avant le dossier suivant.

Les deux routes POST reçoivent limit et cursor dans le corps, et non dans l'adresse.

Ces trois listes donnent aussi un curseur. Pour GET /jobs/{id}/logs, next_cursor vaut null sur la dernière page. Pour le parcours et la recherche, next_cursor est absent sur la dernière page.

Lire une erreur

Toutes les erreurs ont le même corps.

{"error": {"code": "forbidden", "message": "this API key has no operate scope"}}

Écrivez votre code sur le champ code. Le champ message est écrit pour une personne, en anglais, et il peut changer.

Le tableau donne les codes qu'une intégration doit traiter.

Statut	Code	Cause	Ce qu'il faut faire
400	validation_failed	Le corps, un paramètre de requête ou un paramètre de chemin est refusé. Le champ issues nomme les champs en cause.	Corrigez la requête.
400	invalid_request, invalid_path	Une valeur est refusée après le contrôle du schéma : un chemin, un filtre ou une cible.	Corrigez la requête.
401	unauthorized	Clé absente, inconnue, révoquée ou expirée, adresse non autorisée, ou MSP supprimé. L'API donne la même réponse pour toutes ces causes.	Vérifiez la clé et l'adresse d'appel. Ne réessayez pas avec la même clé.
403	forbidden	La route refuse ce type de clé, ou la clé n'a pas la portée.	Utilisez la bonne clé, ou une clé avec la portée.
403	msp_suspended	Le MSP est suspendu.	Réactivez le MSP.
404	not_found	L'objet n'existe pas, ou il appartient à un autre MSP.	Vérifiez l'identifiant.
409	api_key_limit	Le MSP a déjà deux clés vivantes.	Révoquez une clé.
409	msp_limit_reached	L'installation n'accepte qu'un seul MSP.	Contactez l'équipe de la plateforme.
409	no_file_policy	La machine n'a pas de politique de sauvegarde de fichiers avec au moins un chemin.	Créez une politique avec POST /endpoints/{id}/policies.
409	agent_offline	Sauvegarde ou parcours d'une machine qui n'est pas connectée.	Réessayez quand GET /endpoints/{id}/agent donne online.
409	job_active	Une tâche travaille déjà sur ce dépôt.	Attendez la fin de la tâche.
409	repo_not_ready	Le dépôt est en cours de création ou de déplacement.	Réessayez après quelques secondes.
409	restore_in_progress, repo_busy, agent_too_old, original_not_allowed	La restauration ne peut pas démarrer maintenant, ou pas avec cette cible.	Lisez le champ message.
409	cross_client_confirmation_required	Restauration vers une machine d'un autre client. Une clé ne le fait jamais.	Restaurez vers une machine du même client.
409	client_deleting, endpoint_deleting	Une suppression attend son délai de 72 heures.	Annulez d'abord l'action différée, si nécessaire.
404	snapshot_not_found	Le point de restauration n'est plus dans le dépôt.	Listez de nouveau les points de restauration.
415	unsupported_media_type	Le corps n'est pas au format JSON.	Envoyez Content-Type: application/json.
422	path_not_found, not_a_directory, too_many_entries	Parcours : le chemin n'est pas un dossier du point de restauration, ou le dossier est trop grand.	Utilisez la recherche.
429	rate_limited	Trop d'appels.	Attendez le nombre de secondes de Retry-After.
502	snapshot_unreadable	Le point de restauration ne peut pas être lu maintenant.	Réessayez plus tard.
503	browse_busy, agent_busy	Trop de demandes de parcours en même temps.	Attendez le nombre de secondes de Retry-After.
504	browse_timeout, agent_timeout	Aucune réponse dans le délai.	Réessayez plus tard.
500	internal	Erreur du serveur.	Réessayez plus tard. Si l'erreur continue, donnez l'heure de l'appel à l'équipe de la plateforme.

Réessayez un appel seulement sur 409 repo_not_ready, 409 job_active, 409 agent_offline, 429, 502, 503 et 504, après un délai. Ne réessayez pas sur 400, 401, 403 et 404 : la réponse sera la même.

Respecter la limite de débit

Chaque clé a une limite de débit, comptée par serveur d'API : une réserve de 100 appels, puis 10 appels par seconde.

Au-dessus de la limite, l'API répond 429 rate_limited avec l'en-tête Retry-After: 1.

1. Lisez l'en-tête Retry-After de la réponse.
2. Attendez ce nombre de secondes.
3. Refaites l'appel.

Quelques routes ont leur propre limite, plus basse : les demandes de restauration, le parcours d'une machine et le parcours d'un point de restauration. Elles répondent aussi 429 ou 503 browse_busy, avec un en-tête Retry-After.

Limiter les adresses autorisées

Une clé accepte une liste d'adresses. Un appel qui vient d'une autre adresse reçoit 401 unauthorized, comme une clé inconnue.

• Une liste tient au plus 50 entrées.
• Une entrée est une adresse IPv4, une adresse IPv6, un bloc CIDR IPv4 ou un bloc CIDR IPv6. Par exemple 203.0.113.10, 198.51.100.0/24 ou 2001:db8::/32.
• Une liste vide accepte toutes les adresses.

Donnez les adresses de vos serveurs à l'administrateur de la plateforme à la création de la clé.

Renouveler une clé sans coupure

Un MSP a au plus deux clés vivantes. Deux clés permettent un renouvellement sans coupure de service.

1. Demandez le renouvellement de la clé à l'administrateur de la plateforme. La nouvelle clé garde le nom, les portées et les adresses de l'ancienne.
2. Mettez la nouvelle clé dans votre produit. Les deux clés fonctionnent en même temps.
3. Vérifiez que vos appels passent avec la nouvelle clé.
4. Demandez la révocation de l'ancienne clé.

Une clé expire. Par défaut après 365 jours, et au plus après 730 jours. BaaStide ne prolonge pas une clé : renouvelez-la avant cette date.

Retrouver ses appels dans le journal d'audit

Chaque appel écrit une ligne dans le journal d'audit du MSP, avant le travail. Les lignes du travail nomment aussi la clé.

1. Appelez GET /audit-log avec la portée read.
2. Lisez le champ actor_type. La valeur api_key désigne un appel de clé.
3. Lisez le champ actor_api_key : il donne l'identifiant, le nom et le début de la clé.
4. Pour ne garder qu'une clé, ajoutez le paramètre api_key_id.

Donnez un nom clair à chaque intégration. Le journal affiche ce nom. Voir Journal d'audit.

Limites et précautions

• Une clé API est un secret. Gardez-la dans un coffre à secrets. Ne la mettez pas dans une URL, un journal ou une ligne de commande.
• BaaStide affiche une clé une seule fois, à sa création et à son renouvellement. Si la clé est perdue, demandez un renouvellement : personne ne peut la retrouver.
• Le début d'une clé (bst_msp_) permet aux outils de détection de secrets de trouver une clé qui a fuité. Faites révoquer une clé qui a fuité tout de suite.
• Une clé n'atteint jamais une route de la plateforme. Elle ne crée ni ne lit une autre clé.
• Une clé ne gère pas les utilisateurs d'un MSP : ni la liste, ni les invitations, ni les rôles, ni la vérification en deux étapes, ni les réglages de l'accès MCP.
• Une clé n'exporte pas la clé d'un dépôt.
• Une clé ne raccourcit pas et n'approuve pas le délai de 72 heures d'une action destructive. Elle peut seulement annuler une action différée. Voir Délai de 72 heures.
• Une clé ne restaure pas vers une machine d'un autre client, même avec une confirmation.
• Une clé ne lit pas le flux d'événements du portail. Interrogez les routes à la place, par exemple GET /jobs/{id} ou GET /restore-sessions/{id}.
• Une clé d'un MSP suspendu reçoit 403 msp_suspended sur toutes les routes, sauf GET /msp.
• Un objet d'un autre MSP répond 404 not_found, et jamais 403. L'API ne dit pas si cet objet existe.

Référence

• Routes de l'API REST : API.
• Le MSP de la clé : Get current msp.
• Journal d'audit : List audit log.