Démarrage rapide de l'API

Les clés d’API permettent à vos scripts et à votre CI d’agir pour votre organisation. Chaque clé ne porte que les portées que vous lui donnez.

Créer une clé

1. Activez l’authentification à deux facteurs dans Settings. Elle est requise pour créer une clé.
2. Dans la console, ouvrez Keys et choisissez Create key.
3. Nommez la clé d’après ce qui l’utilise, par exemple ci-runner.
4. Choisissez ses portées et sa durée de vie : 30, 90, 180 ou 365 jours.
5. Facultatif : fixez ses plafonds de dépenses (voir plus bas).
6. Copiez la clé. Elle n’est affichée qu’une fois.

Les propriétaires et les administrateurs de l’organisation gèrent les clés. Chaque nouvelle clé est annoncée par courriel à la personne qui l’a créée.

S’authentifier

Envoyez la clé comme jeton Bearer :

export NODELODGE_API_KEY="nl_live_..."
curl https://nodelodge.com/v1/whoami \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

La réponse indique l’organisation et les portées de la clé :

{
  "orgId": "6f1c...",
  "via": "api_key",
  "apiKeyId": "2b9e...",
  "scopes": ["workloads:read"]
}

Appelez whoami dans un pipeline pour échouer tôt sur une clé révoquée, expirée ou mal saisie.

Référence

Chaque point de terminaison, avec ses paramètres et un exemple curl, figure dans la référence de l’API. La même description est publiée en document OpenAPI 3.1 à l’adresse https://nodelodge.com/v1/openapi.json : importez-la dans votre client HTTP, ou générez-en un client typé.

curl https://nodelodge.com/v1/openapi.json -o nodelodge-openapi.json

Portées

Donnez à chaque clé le minimum de portées dont sa tâche a besoin. Une clé qui ne fait que remonter un état n’a besoin que de workloads:read.

Ce qu’une clé peut appeler

Une clé relève le budget et lit les informations de connexion des seules sessions qu’elle a lancées. Toute clé de l’organisation dotée de workloads:write peut arrêter une session.

Lancer une session

curl -X POST https://nodelodge.com/v1/sessions \
  -H "Authorization: Bearer $NODELODGE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"partnerOfferId":"3f0c8f5e-8c3a-4f39-9a8e-2d9b4c1e7a10","environmentId":"jupyterlab","pricing":"on_demand","budgetCents":2000,"allowedCidr":"203.0.113.7","sshPublicKey":"ssh-ed25519 AAAA... you@laptop"}'

• budgetCents est le coût maximal de la session. Il est réservé sur votre crédit au lancement. La facturation suit le temps réel d’exécution de la machine, dès qu’elle est prête, et Budget Guard arrête la session avant que le budget soit dépensé.
• allowedCidr est l’adresse IPv4 publique, ou une plage jusqu’à /24, autorisée à se connecter en SSH.
• sshPublicKey ouvre cette session seulement : la clé n’est pas enregistrée sur votre compte. Pour utiliser une clé enregistrée dans la console, envoyez plutôt son identifiant dans sshKeyIds. L’enregistrement et la suppression d’une clé de votre compte se font dans la console.
• environmentId : les machines en centre de données exécutent jupyterlab. GET /v1/environments?offerId=... liste ce qu’une machine Community peut exécuter.
• Ajoutez maxDurationHours pour arrêter la session après ce nombre d’heures, même s’il reste du budget.
• L’en-tête Idempotency-Key garantit qu’une requête relancée ne démarre qu’une session.

Lisez la session avec GET /v1/sessions/{id} : une fois son état à ready, directSsh donne l’hôte, l’utilisateur et le port. Relevez son budget avec POST /v1/sessions/{id}/budget et arrêtez-la avec POST /v1/sessions/{id}/stop : la facturation s’arrête et le reste du budget est libéré.

Si POST /v1/sessions répond 409 RESERVATION_REQUIRED, réservez la machine avec POST /v1/reservations (partnerOfferId et durationHours, ou mode: "on_demand"), puis démarrez-la avec POST /v1/reservations/{id}/start. Une durée fixe bloque son prix complet, et maxCostCents refuse la réservation si ce montant le dépasse. À la demande, le montant bloqué couvre les 60 prochaines minutes et se renouvelle tant que la machine tourne. Dans les deux cas, vous êtes facturé par minute entamée d’utilisation réelle, sans minimum d’une heure.

Pour piloter des sessions depuis un agent d’IA, utilisez le serveur MCP.

Plafonds de dépenses

Chaque clé peut porter des plafonds, appliqués par Node Lodge au lancement d’une session, à chaque hausse de son budget et à chaque prolongation d’une réservation à la demande :

Un lancement ou une hausse qui dépasserait un plafond renvoie 409 API_KEY_LIMIT et ne réserve rien. Les requêtes simultanées d’une même clé sont vérifiées l’une après l’autre : elles ne peuvent pas dépasser un plafond ensemble. Une clé sans plafond reste bornée par votre crédit disponible et les limites de votre compte. Les propriétaires et les administrateurs modifient les plafonds d’une clé active avec Edit limits dans Keys, après un code à deux facteurs récent. Les sessions lancées depuis la console ne sont limitées par aucune clé.

Les paramètres du compte, les clés, les clés SSH enregistrées, les cartes et l’authentification à deux facteurs restent dans la console : une requête avec une clé d’API sur ces routes renvoie 403 API_KEY_NOT_ALLOWED. Chaque action effectuée avec une clé figure dans Activity, avec la clé qui l’a faite.

Erreurs

Les corps d’erreur ont partout la même forme :

{ "error": { "code": "API_KEY_NOT_ALLOWED", "message": "...", "reference": "7F3K-92QD" } }

reference identifie la requête. Journalisez-la avec l’erreur et indiquez-la quand vous écrivez au support.

Protéger vos clés

• Stockez les clés dans votre gestionnaire de secrets ou les secrets de votre CI, jamais dans le code.
• Une clé par outil : vous en révoquez une sans toucher aux autres.
• Révoquez une clé dans Keys dès qu’elle fuite. Les requêtes qui l’utilisent s’arrêtent immédiatement.
• Chaque création et révocation de clé figure dans Activity.