Jetons API Orbit et l'API REST

Les jetons API permettent à un script, un pipeline CI ou vos propres outils de piloter Orbit sans session navigateur : déclencher des déploiements, signaler les résultats des vérifications CI, télécharger les artefacts de compilation, gérer les tâches cron et bien plus encore, le tout authentifié avec un jeton Bearer que vous délimitez vous-même.

Où se trouvent les jetons

Ouvrez Orbit et choisissez Tokens dans la navigation de haut niveau. La page s'intitule API Access Tokens et énonce sa propre règle d'entrée : les jetons s'affichent une seule fois à la création.

La documentation complète des points de terminaison se trouve à un clic. La carte API Reference dispose d'un bouton View docs qui ouvre la référence intégrée au panneau pour chaque point de terminaison Orbit.

Créer un jeton

1. Cliquez sur New token.
2. Donnez-lui un Token name. Nommez-le d'après ce qui l'utilisera, par exemple le workflow CI, pour que l'inventaire soit lisible ultérieurement.
3. Choisissez ses Scopes.
4. Définissez éventuellement une Expiry. Laissez-la vide pour un jeton qui n'expire pas.
5. Cliquez sur Create token.

Le jeton brut s'affiche une seule fois, sous un en-tête One-time reveal, avec un bouton de copie. Collez-le directement dans votre magasin de secrets CI. Il n'y a aucun moyen de le voir à nouveau : seul un hachage SHA-256 du jeton est stocké, donc même Kapsule ne peut pas le récupérer pour vous.

Un compte peut contenir jusqu'à 20 jetons actifs. La création d'un vingt-et-unième est refusée avec un message vous demandant de révoquer d'abord un jeton existant.

Étendues

Les étendues sont le cœur même des jetons : chacun n'a que les permissions que vous lui avez accordées.

Un nouveau jeton utilise par défaut deploy:write et project:read, ce dont un pipeline de déploiement a besoin et rien de plus.

Accordez l'ensemble le plus petit qui fait le travail. Un jeton qui a seulement besoin de signaler un résultat CI n'a pas besoin de project:write. Un script de surveillance en lecture seule n'a besoin d'aucune étendue d'écriture. Chaque point de terminaison dans la référence énumère l'étendue minimale qu'il nécessite.

Utiliser un jeton

L'authentification est un en-tête Bearer par rapport à la base API, https://kapsulehost.com :

curl -X POST https://kapsulehost.com/api/orbit/$ORBIT_PROJECT_ID/deployments \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main"}'

La page Tokens contient un extrait CI/CD usage prêt à l'emploi et un workflow de démarrage GitHub Actions. Le démarrage est enregistré en tant que .github/workflows/orbit-deploy.yml et nécessite deux secrets de dépôt, ORBIT_TOKEN et ORBIT_PROJECT_ID. Copiez les deux depuis la page plutôt que de les transcrire.

Ce que couvre l'API

La référence intégrée au panneau documente chaque zone avec ses paramètres et l'étendue requise :

• Deployments : déclencher un déploiement, éventuellement sur une branche nommée, éventuellement programmé pour une heure future entre cinq minutes et trente jours à l'avance, avec une note d'au maximum 500 caractères. La liste supporte la recherche floue sur le commit, le message, la branche et l'auteur, plus des filtres sur la branche, le statut et l'environnement, avec pagination par curseur jusqu'à 100 résultats par page.
• Deployment checks : enregistrer une porte de qualité au début de votre travail CI, puis signaler le résultat quand il se termine. Une vérification required qui échoue change le déploiement en FAILED et revient l'environnement au déploiement réussi précédent, ce qui vous permet de faire de votre propre suite de tests une véritable porte de déploiement.
• Branch protection : règles de motif glob qui bloquent les déploiements automatiques jusqu'à ce que les vérifications requises réussissent et, éventuellement, que quelqu'un approuve. Jusqu'à dix règles par projet.
• Build artifacts : obtenir une URL de téléchargement pré-signée pour la sortie compilée d'un déploiement réussi. L'URL est valide pendant quinze minutes.
• Project transfer : initier, annuler et vérifier l'état d'un transfert vers un autre compte. Consultez Transferring an Orbit Project.
• Cron jobs : lister, créer, mettre à jour, supprimer, déclencher et lire l'historique d'exécution. Consultez Orbit Cron Jobs.
• Timeline annotations : créer et gérer les annotations d'incident, de publication, de jalon, de note et d'indicateur. Consultez Orbit Timeline Annotations.
• Status page : lire et écrire la configuration de la page d'état publique. Consultez Orbit Status Page.
• Edge functions : lister, créer, mettre à jour et déployer des gestionnaires de bord. Consultez Orbit Edge Functions.

L'authentification par session depuis le panneau fonctionne aux côtés des jetons Bearer, donc un point de terminaison que vous pouvez appeler depuis votre navigateur peut généralement aussi être appelé depuis un script.

Cache de compilation distant Turbo

La page Tokens contient aussi une carte Remote Build Cache. Elle implémente le protocole Turborepo Remote Cache Protocol, permettant à un monorépôt de partager les caches de compilation entre les exécutions CI et les machines de développement.

Activez-le sur la carte, copiez le jeton qu'il génère, et définissez-le aux côtés de votre ID de compte en tant que TURBO_TEAM dans votre environnement CI. Les artefacts jusqu'à 150 Mo chacun sont acceptés. La carte offre également Rotate token et Disable.

Si le CI de votre monorépôt passe la plupart de son temps à reconstruire des packages qui n'ont pas changé, c'est la chose la plus précieuse de cette page.

Gérer l'inventaire

L'inventaire de jetons énumère chaque jeton actif avec :

• Quand il a été Created.
• Quand il a été Last used, ou Never.
• Quand il Expires, avec un badge expired une fois qu'il a expiré.

La colonne Last used est celle à auditer. Un jeton qui n'a jamais été utilisé est soit mal configuré, soit oublié, et de toute façon c'est une credential qui traîne sans rien faire. L'indice de la page le dit clairement : révoquez tout ce que vous ne reconnaissez pas.

Révoquer un jeton

Cliquez sur le contrôle de révocation sur la ligne. La confirmation est explicite : tout ce qui s'authentifie avec ce jeton perd l'accès immédiatement, et cela ne peut pas être annulé.

Révoquez quand un pipeline est retiré, quand quelqu'un ayant accès à vos secrets CI s'en va, ou dès que vous soupçonnez qu'un jeton a été divulgué. Il n'y a pas de révocation partielle et pas de période de grâce, ce qui est exactement ce que vous voulez dans le cas d'une fuite.

Dépannage

401 Unauthorized. L'en-tête est incorrect ou le jeton a été révoqué ou a expiré. Vérifiez que l'en-tête est Authorization: Bearer <token> avec un seul espace, et que votre secret CI n'a pas de retour à la ligne.

403 Forbidden. Le jeton est valide mais manque l'étendue pour ce point de terminaison. La référence énumère l'étendue minimale par point de terminaison. Les étendues sont fixes à la création, donc créez un nouveau jeton avec l'ensemble correct.

429 at creation. Vous êtes au limite de vingt jetons. Révoquez quelque chose de l'inventaire.

The artifact URL stops working. Les URL pré-signées durent quinze minutes. Demandez une nouvelle URL plutôt que de stocker l'URL.

A scheduled deployment is rejected. L'heure programmée doit être entre cinq minutes et trente jours dans le futur.

Où aller ensuite

• Deploying Your Project pour voir ce qu'un déploiement déclenché fait réellement.
• Orbit Deployment Pipeline pour voir quelles portes vos déploiements API vont franchir.
• Orbit Plan Limits pour voir ce que votre plan inclut.