API-Schnellstart

Mit API-Schlüsseln handeln Ihre eigenen Skripte und Ihre CI im Namen Ihrer Organisation. Jeder Schlüssel trägt nur die Scopes, die Sie ihm geben.

Schlüssel erstellen

1. Aktivieren Sie die Zwei-Faktor-Authentifizierung unter Settings. Ohne sie lässt sich kein Schlüssel erstellen.
2. Öffnen Sie in der Konsole Keys und wählen Sie Create key.
3. Benennen Sie den Schlüssel nach seinem Verwendungszweck, zum Beispiel ci-runner.
4. Wählen Sie seine Scopes und seine Laufzeit: 30, 90, 180 oder 365 Tage.
5. Legen Sie optional seine Ausgabenlimits fest (siehe unten).
6. Kopieren Sie den Schlüssel. Er wird nur einmal angezeigt.

Owner und Admins der Organisation verwalten die Schlüssel. Jeder neue Schlüssel wird der Person, die ihn erstellt hat, per E-Mail gemeldet.

Authentifizieren

Senden Sie den Schlüssel als Bearer-Token:

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

Die Antwort nennt die Organisation und die Scopes des Schlüssels:

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

Nutzen Sie whoami in einer Pipeline, damit ein widerrufener, abgelaufener oder falsch eingegebener Schlüssel sofort auffällt.

Referenz

Jeder Endpoint mit seinen Parametern und einem curl-Beispiel steht in der API-Referenz. Dieselbe Beschreibung ist als OpenAPI-3.1-Dokument unter https://nodelodge.com/v1/openapi.json veröffentlicht: Importieren Sie es in Ihren HTTP-Client oder generieren Sie daraus einen typisierten Client.

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

Scopes

Geben Sie jedem Schlüssel nur die Scopes, die seine Aufgabe braucht. Ein Schlüssel, der nur den Status meldet, braucht workloads:read.

Was ein Schlüssel aufrufen kann

Ein Schlüssel erhöht das Budget und liest die Verbindungsdaten nur der Sitzungen, die er gestartet hat. Jeder Schlüssel der Organisation mit workloads:write kann eine Sitzung stoppen.

Eine Sitzung starten

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 ist der Höchstbetrag der Sitzung. Er wird beim Start auf Ihrem Guthaben reserviert. Abgerechnet wird die tatsächliche Laufzeit der Maschine ab dem Moment, in dem sie bereit ist, und Budget Guard stoppt die Sitzung, bevor das Budget aufgebraucht ist.
• allowedCidr ist die öffentliche IPv4-Adresse oder ein Bereich bis /24, der sich per SSH verbinden darf.
• sshPublicKey öffnet nur diese Sitzung: Der Schlüssel wird nicht in Ihrem Konto gespeichert. Um einen in der Konsole gespeicherten Schlüssel zu nutzen, senden Sie stattdessen seine ID in sshKeyIds. Schlüssel speichern oder aus Ihrem Konto entfernen Sie in der Konsole.
• environmentId: Rechenzentrumsmaschinen führen jupyterlab aus. GET /v1/environments?offerId=... listet, was eine Community-Maschine ausführen kann.
• Mit maxDurationHours stoppt die Sitzung nach dieser Anzahl Stunden, auch wenn noch Budget übrig ist.
• Der Idempotency-Key-Header sorgt dafür, dass ein wiederholter Request nur eine Sitzung startet.

Lesen Sie die Sitzung mit GET /v1/sessions/{id}: Sobald ihr Status ready ist, liefert directSsh Host, Benutzer und Port. Erhöhen Sie ihr Budget mit POST /v1/sessions/{id}/budget und stoppen Sie sie mit POST /v1/sessions/{id}/stop: Die Abrechnung endet, und der Rest des Budgets wird freigegeben.

Antwortet POST /v1/sessions mit 409 RESERVATION_REQUIRED, buchen Sie die Maschine mit POST /v1/reservations (partnerOfferId und durationHours, oder mode: "on_demand") und starten Sie sie mit POST /v1/reservations/{id}/start. Eine feste Dauer reserviert ihren vollen Preis, und maxCostCents lehnt die Buchung ab, wenn dieser Betrag den Wert überschreiten würde. On demand deckt der reservierte Betrag die nächsten 60 Minuten und wird verlängert, solange die Maschine läuft. In beiden Fällen wird pro angefangener Minute tatsächlicher Nutzung abgerechnet, ohne Mindestdauer von einer Stunde.

Um Sitzungen über einen KI-Agenten zu steuern, nutzen Sie den MCP-Server.

Ausgabenlimits

Jeder Schlüssel kann Limits tragen. Node Lodge setzt sie beim Start einer Sitzung, bei jeder Erhöhung ihres Budgets und bei jeder Verlängerung einer On-demand-Buchung durch:

Ein Start oder eine Erhöhung, die ein Limit überschreiten würde, erhält 409 API_KEY_LIMIT und reserviert nichts. Gleichzeitige Requests mit einem Schlüssel werden nacheinander geprüft, sodass sie ein Limit nicht gemeinsam überschreiten können. Ein Schlüssel ohne Limits bleibt durch Ihr verfügbares Guthaben und Ihre Kontolimits begrenzt. Owner und Admins ändern die Limits eines aktiven Schlüssels mit Edit limits unter Keys, nach Eingabe eines neuen Zwei-Faktor-Codes. In der Konsole gestartete Sitzungen unterliegen keinem Schlüssel-Limit.

Kontoeinstellungen, Schlüssel, gespeicherte SSH-Schlüssel, Karten und Zwei-Faktor-Authentifizierung bleiben in der Konsole: Ein Request mit API-Schlüssel darauf erhält 403 API_KEY_NOT_ALLOWED. Jede Aktion mit einem Schlüssel erscheint unter Activity, mit dem Schlüssel, der sie ausgelöst hat.

Fehler

Fehler-Bodys haben überall dieselbe Form:

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

reference identifiziert den Request. Protokollieren Sie ihn mit dem Fehler und geben Sie ihn an, wenn Sie dem Support schreiben.

Schlüssel schützen

• Speichern Sie Schlüssel in Ihrem Secret Manager oder in den CI-Secrets, nie im Code.
• Ein Schlüssel pro Tool: So widerrufen Sie einen, ohne die anderen anzutasten.
• Widerrufen Sie einen Schlüssel unter Keys, sobald er geleakt ist. Requests damit enden sofort.
• Jede Erstellung und jeder Widerruf eines Schlüssels steht unter Activity.