L’API OrbitLab donne un accès programmatique à tout ce que vous gérez dans le tableau de bord : services et déploiements, variables d’environnement, journaux et métriques, domaines et DNS, bases de données, fichiers, outils WordPress, organisations, commandes et renouvellements. La CLI repose sur cette API.
Retrouvez tous les points d’accès dans la section API reference du menu.
URL de base
Les requêtes et réponses sont en JSON, sauf mention contraire (les journaux sont en text/plain, les factures en PDF, les envois de fichiers en multipart/form-data).
Authentification
Authentifiez-vous avec un jeton d’API dans l’en-tête Authorization :
Créer un jeton
- Ouvrez Tableau de bord → Paramètres → Jetons d’API.
- Cliquez sur Créer un jeton, nommez-le et choisissez :
- Portée : toutes vos organisations, ou une seule.
- Expiration : 30, 90 ou 365 jours, ou aucune.
- Copiez le jeton. Il commence par
olab_ et n’est affiché qu’une seule fois.
orbitlab login crée de la même façon un jeton pour la CLI, après votre approbation dans le navigateur. Les jetons créés par la CLI expirent au bout de 90 jours.
Un jeton agit avec vos permissions : il peut faire ce que votre rôle autorise dans chaque organisation. OrbitLab ne conserve qu’une empreinte du jeton. Révoquez les jetons inutilisés depuis la même page, ou avec DELETE /v1/tokens/{id}. Un jeton cesse de fonctionner immédiatement lorsqu’il est révoqué, lorsqu’il expire ou lorsque vous quittez l’organisation à laquelle il est limité.
Protégez vos jetons comme des mots de passe : conservez-les dans le coffre à secrets de votre CI, jamais dans votre dépôt.
Actions réservées au tableau de bord
Par sécurité, certaines actions nécessitent une connexion au tableau de bord et ne sont pas possibles avec un jeton : créer des jetons, supprimer votre compte, dissocier une méthode de connexion et installer l’application GitHub.
Organisations
Les ressources appartiennent à des organisations. Les requêtes agissent sur votre première organisation, sauf si vous en choisissez une autre avec l’en-tête X-OrbitLab-Org (identifiant ou slug) :
Un jeton limité à une organisation agit toujours sur celle-ci ; en choisir une autre renvoie 403. Listez vos organisations avec GET /v1/organizations.
Certains points d’accès exigent le rôle propriétaire ou administrateur, par exemple pour lire les variables d’environnement et les identifiants de base de données, modifier le DNS ou gérer les membres. La référence de l’API indique le rôle requis pour chaque point d’accès.
Conventions
- Les identifiants sont des UUID, sauf ceux des formules (
app-1, starter…) et des enregistrements DNS.
- Les montants sont des entiers en centimes, accompagnés d’une
currency.
- Les dates sont des chaînes ISO 8601 en UTC.
- Les collections sont renvoyées entières sous une clé nommée, par exemple
{ "services": [...] }.
Erreurs
Les erreurs renvoient un statut HTTP et un corps JSON contenant un message error :
Commande idempotente
POST /v1/checkout crée une commande et lance le paiement. Envoyez un en-tête Idempotency-Key unique : une requête relancée renverra la même commande au lieu d’en créer une nouvelle.
Exemples
Déployer un service et suivre le déploiement :
Définir des variables d’environnement :
Ajouter un enregistrement DNS :
Commander une application payée par Mobile Money :
Une demande de paiement est envoyée au téléphone. Interrogez GET /v1/orders/{orderId} jusqu’à ce que la commande soit paid. Le paiement par carte est actuellement indisponible ; une commande gratuite ne nécessite pas de numéro.
Connexion par appareil pour vos outils
Les outils qui ne peuvent pas stocker de jeton à l’avance peuvent utiliser la même connexion par appareil que la CLI :
POST /v1/auth/device avec {"clientName": "mon-outil"} renvoie deviceCode, userCode et verificationUriComplete.- Affichez le code et le lien à l’utilisateur, qui approuve la demande dans le tableau de bord.
- Interrogez
POST /v1/auth/device/token avec {"deviceCode": "…"} toutes les interval secondes. En attendant, la réponse est 400 avec "error": "authorization_pending" ; en cas de "slow_down", ajoutez 5 secondes à l’intervalle. Une fois la demande approuvée, le token est renvoyé une seule fois.