Kapsule Orbit API-Tokens und die REST-API

Orbit API-Token und die REST API

API-Token ermöglichen es einem Skript, einer CI-Pipeline oder deinem eigenen Tool, Orbit ohne Browser-Sitzung zu steuern: Deployments auslösen, CI-Prüfergebnisse melden, Build-Artefakte herunterladen, Cron-Jobs verwalten und vieles mehr, alles authentifiziert mit einem Bearer-Token, dessen Umfang du selbst festlegst.

Wo Token gespeichert sind

Öffne Orbit und wähle Tokens aus der Top-Level-Navigation. Die Seite trägt den Titel API Access Tokens und gibt die Regel gleich zu Anfang an: Token werden bei der Erstellung nur einmal angezeigt.

Die vollständige Endpunkt-Dokumentation ist einen Klick entfernt. Die Karte API Reference hat einen Button View docs, der die In-Panel-Referenz für jeden Orbit-Endpunkt öffnet.

Token erstellen

1. Klicke auf New token.
2. Gib einen Token name ein. Benenne ihn nach dem, das ihn verwendet, zum Beispiel nach dem CI-Workflow, damit die Übersicht später lesbar ist.
3. Wähle seine Scopes.
4. Stelle optional eine Expiry ein. Lasse das Feld leer für einen Token, der nicht abläuft.
5. Klicke auf Create token.

Der rohe Token wird einmal angezeigt, unter einer Überschrift One-time reveal, mit einem Kopieren-Button. Füge ihn direkt in deinen CI-Secret-Store ein. Es gibt keine Möglichkeit, ihn später zu sehen: Nur ein SHA-256-Hash des Tokens wird gespeichert, daher kann auch KapsuleHost ihn für dich nicht wiederherstellen.

Ein Konto kann bis zu 20 aktive Token halten. Das Erstellen eines einundzwanzigsten Token wird abgelehnt mit einer Nachricht, die dich auffordert, zuerst einen vorhandenen zu widerrufen.

Scopes

Scopes sind der Sinn von Token: Jeder hat nur die Berechtigungen, die du ihm gegeben hast.

Ein neuer Token hat standardmäßig deploy:write und project:read, was eine Deployment-Pipeline braucht und nichts mehr.

Gewähre den kleinstmöglichen Satz, der den Job macht. Ein Token, der nur ein CI-Ergebnis melden muss, braucht nicht project:write. Ein schreibgeschütztes Monitoring-Skript braucht keinen Write-Scope. Jeder Endpunkt in der Referenz listet den minimalen Scope auf, den er benötigt.

Token verwenden

Authentifizierung ist ein Bearer-Header gegen die API-Basis, 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"}'

Die Tokens-Seite enthält ein vorgefertigtes CI/CD usage-Snippet und einen GitHub Actions starter-Workflow. Der Starter wird als .github/workflows/orbit-deploy.yml gespeichert und benötigt zwei Repository-Secrets, ORBIT_TOKEN und ORBIT_PROJECT_ID. Kopiere beide von der Seite, anstatt sie abzutippen.

Was die API abdeckt

Die In-Panel-Referenz dokumentiert jeden Bereich mit seinen Parametern und erforderlichem Scope:

• Deployments: Löse ein Deployment aus, optional auf einem benannten Branch, optional geplant für einen zukünftigen Zeitpunkt zwischen fünf Minuten und dreißig Tagen im Voraus, mit einer Notiz bis zu 500 Zeichen. Das Listing unterstützt Fuzzy-Suche über Commit, Nachricht, Branch und Autor sowie Filter für Branch, Status und Umgebung mit Cursor-Paginierung bis zu 100 Ergebnissen pro Seite.
• Deployment checks: Registriere ein Quality Gate am Anfang deines CI-Jobs und melde das Ergebnis, wenn er fertig ist. Ein erforderlicher Check, der fehlschlägt, verschiebt das Deployment zu FAILED und setzt die Umgebung auf das letzte erfolgreiche Deployment zurück, so machst du deine eigene Test-Suite zu einem echten Deploy-Gate.
• Branch protection: Glob-Pattern-Regeln, die automatische Deployments blockieren, bis erforderliche Checks erfolgreich sind und optional jemand genehmigt. Bis zu zehn Regeln pro Projekt.
• Build artifacts: Rufe eine vorsignierte Download-URL für die kompilierte Ausgabe eines erfolgreichen Deployments ab. Die URL ist fünfzehn Minuten lang gültig.
• Project transfer: Initiiiere, breche ab und prüfe den Status einer Übertragung auf ein anderes Konto. Siehe Übertragung eines Orbit-Projekts.
• Cron jobs: Liste, erstelle, aktualisiere, lösche, starte aus und lese Ausführungsverlauf. Siehe Orbit Cron Jobs.
• Timeline annotations: Erstelle und verwalte Incident-, Release-, Milestone-, Note- und Flag-Anmerkungen. Siehe Orbit Timeline Annotations.
• Status page: Lese und schreibe die Konfiguration der öffentlichen Statusseite. Siehe Orbit Status Page.
• Edge functions: Liste, erstelle, aktualisiere und deploye Edge-Handler. Siehe Orbit Edge Functions.

Sitzungsauthentifizierung aus dem Panel funktioniert neben Bearer-Token, daher kann ein Endpunkt, den du von deinem Browser aufrufen kannst, normalerweise auch von einem Skript aus aufgerufen werden.

Turbo Remote Cache

Die Tokens-Seite enthält auch eine Karte Remote Build Cache. Sie implementiert das Turborepo Remote Cache Protocol, das es einem Monorepo ermöglicht, Build-Caches zwischen CI-Läufen und Entwicklermaschinen zu teilen.

Aktiviere es auf der Karte, kopiere den Token, den es generiert, und setze ihn zusammen mit deiner Account-ID als TURBO_TEAM in deine CI-Umgebung. Artefakte bis zu 150 MB werden akzeptiert. Die Karte bietet auch Rotate token und Disable.

Wenn dein Monorepo-CI den größten Teil seiner Zeit damit verbringt, Packages neu zu erstellen, die sich nicht geändert haben, ist dies das Wertvollste auf der Seite.

Verwaltung des Bestands

Das Token inventory listet jeden aktiven Token auf mit:

• Wann er Created wurde.
• Wann er Last used wurde oder Never.
• Wann er Expires, mit einem expired-Badge sobald er abgelaufen ist.

Die Spalte Last used ist die zu prüfende. Ein Token, der niemals verwendet wurde, ist entweder fehlkonfiguriert oder vergessen, und in jedem Fall ist es ein Anmeldedaten, die herumliegen und nichts tun. Der Hinweis der Seite selbst sagt es deutlich: Widerrufe alles, das du nicht erkennst.

Token widerrufen

Klicke auf das Widerrufen-Control in der Reihe. Die Bestätigung ist eindeutig: Alles, das sich mit diesem Token authentifiziert, verliert sofort Zugriff, und dies kann nicht rückgängig gemacht werden.

Widerrufe, wenn eine Pipeline eingestellt wird, wenn jemand mit Zugang zu deinen CI-Secrets das Unternehmen verlässt, oder sobald du vermutest, dass ein Token durchgesickert ist. Es gibt keine teilweise Widerrufung und keine Kulanzfrist, was genau das ist, das du im Leak-Fall brauchst.

Fehlerbehebung

401 Unauthorized. Der Header ist falsch oder der Token wurde widerrufen oder ist abgelaufen. Prüfe, dass der Header Authorization: Bearer <token> mit einem einzelnen Leerzeichen ist, und dass dein CI-Secret keinen nachgestellten Zeilenumbruch hat.

403 Forbidden. Der Token ist gültig, aber hat nicht den Scope für diesen Endpunkt. Die Referenz listet den minimalen Scope pro Endpunkt auf. Scopes sind bei der Erstellung festgelegt, daher erstelle einen neuen Token mit dem richtigen Satz.

429 on creation. Du hast das Limit von zwanzig Token erreicht. Widerrufe etwas aus dem Bestand.

The artifact URL stops working. Vorsignierte URLs halten fünfzehn Minuten. Fordere eine frische an, anstatt die URL zu speichern.

A scheduled deployment is rejected. Die geplante Zeit muss zwischen fünf Minuten und dreißig Tagen in der Zukunft liegen.

Nächste Schritte

• Bereitstellung deines Projekts für das, was ein ausgelöstes Deployment tatsächlich bewirkt.
• Orbit Deployment Pipeline um zu sehen, welche Gates deine API-Deployments durchlaufen.
• Orbit Plan Limits für das, das dein Plan umfasst.