API Schlüssel

API Keys nutzen rollenbasierte Zugriffskontrolle (RBAC). Ein Key kann eine organisationsweite Rolle, App-spezifische Bindings oder beides haben. Jedes App-Binding bleibt der jeweiligen Organisation zugeordnet. Um das Prinzip der geringsten Berechtigung (Least Privilege) einzuhalten, beschränke einen Key am besten auf ausgewählte Apps, anstatt eine organisationsweite Rolle zu vergeben.

Wo werden die API-Keys verwaltet?

Navigiere zu Einstellungen > Organisation > API Keys unter console.capgo.app/settings/organization/api-keys.

Die Seite zeigt zwei Bereiche:

• RBAC-Keys — Keys mit zugewiesenen Rollen (empfohlen). Diese Keys nutzen das neue rollenbasierte Berechtigungssystem.
• Alte Keys — Ältere Keys, die das einfache, auf Modi basierende System nutzen (read, upload, write, all) ohne Rollenzuweisungen.

Wie erstelle ich einen neuen API Key?

1. Klicke auf das ”+” Button oben in der RBAC-Key-Tabelle.

2. Fülle die Key-Informationen aus:

   • Name (erforderlich) — Ein beschreibender Name für den Key (z. B. „CI/CD Deploy“ oder „Monitoring Read-Only“).
   • Sicheren Key erstellen (optional) — Wenn aktiviert, wird der Key serverseitig gehasht. Der Plain-Text-Key wird nur einmal nach der Erstellung und können später nicht mehr abgerufen werden.
   • Ablaufdatum festlegen (optional) — Wähle ein Datum, nach dem der Key nicht mehr gültig ist. Einige Organisationen erzwingen ein Ablaufdatum per Policy.

3. Wähle den Key-Scope:

   • Organisationsweiter Zugriff — Wähle eine Organisationsrolle um die Basisberechtigungen für die gesamte Organisation festzulegen. Die verfügbaren Rollen hängen von deinem eigenen Rollenlevel ab:
     • Keine — Kein organisationsweiter Zugriff.
     • Mitglied — Basis-Lesezugriff auf die Organisation.
     • Admin — Voller administrativer Zugriff auf die Organisation und alle zugehörigen Apps.
   • Nur-App-Zugriff — Aktivieren Diesen Key auf ausgewählte Apps beschränken. Jede App-Bindung bleibt mit der Organisation der jeweiligen App verknüpft; dieser Modus verzichtet lediglich auf eine organisationsweite RBAC-Rolle.

4. Falls der Key über das öffentliche API Organisationen erstellen muss, aktiviere Organisationen erstellen erlauben.

   Dies fügt die globale org.create Berechtigung hinzu. Der Key benötigt zudem ein organisationsbezogenes org_admin oder org_super_admin Binding. Wähle im Dashboard Admin erstellt die org_admin Bindung. Wenn dieser Key eine neue Organisation erstellt, weist Capgo den Key automatisch als Super Admin für diese neue Organisation zu.

5. Um App-Zugriff zu gewähren:

   • Wenn Diesen Key auf ausgewählte Apps beschränken ist aktiviert, wähle eine Organisation unter Organisationen, um Apps zu filtern um deren Apps anzuzeigen. Die ausgewählten App-Bindings bleiben mit ihren jeweiligen Organisationen verknüpft; dieser Filter gewährt keinen organisationsweiten Zugriff.
   • Klicken ”+ App hinzufügen”, wähle eine oder mehrere Apps aus und weise jeder eine Rolle zu:
     • App-Reader — Nur Lesezugriff auf die App.
     • App-Uploader — Kann neue Bundles hochladen.
     • App-Entwickler — Kann Bundles hochladen, Geräte verwalten, Native Builds triggern und Channel-Einstellungen ändern.
     • App-Admin — Vollzugriff auf die App.
     • App-Vorschau — CI/CD-Lifecycle testen: Ein Bundle hochladen und einen Preview-Channel erstellen. Der Channel erhält automatisch nur die für diesen Key spezifischen Lifecycle-Rechte.

6. Klicken „Erstellen“.

7. Wenn du ausgewählt hast Sicheren Key erstellen, wird der Key im Klartext in einem Modal angezeigt. Sofort kopieren — nach dem Schließen des Modals kann er nicht mehr abgerufen werden.

App Preview Key für Preview-Workflows nutzen

Nutzt App-Vorschau für CI-Pipelines, die einen temporären, nicht öffentlichen Preview-Channel erstellen, ein Bundle uploaden und promoten und anschließend sowohl den Channel als auch das Bundle wieder löschen. Er hat keinen Lifecycle-Zugriff auf bestehende Default- oder Main-Channels.

1. RBAC-Key erstellen und aktivieren Diesen Key auf ausgewählte Apps beschränken.
2. Unter Organisationen zum Filtern der Apps, wähle die Organisation aus, um deren Apps anzuzeigen; jede ausgewählte App bleibt mit ihrer jeweiligen Organisation verknüpft.
3. Füge nur die App oder Apps hinzu, die für Preview-Deployments genutzt werden.
4. Wähle App-Vorschau für jede ausgewählte App.
5. Erstelle einen sicheren Key, setze bei Bedarf ein Ablaufdatum und speichere ihn in deinem CI Secret Manager.

Dieser Modus (nur ausgewählte Apps) verzichtet auf eine organisationsweite Rolle; er es nicht entfernt die Organisationszugehörigkeit. Jede app_preview Bindung bleibt auf die ausgewählte App und die zugehörige Organisation beschränkt.

Erteilen	Berechtigungen und Grenzen
app_preview für die ausgewählte App	app.read, app.read_bundles, app.upload_bundle, und app.create_channel.
Automatisch channel_preview Bindung	Wenn dieser Key einen Channel erstellt, weist Capgo dem Key automatisch Rechte channel.read, channel.promote_bundle, und channel.delete nur für diesen Channel zu.

app_preview behält app.read, sodass der Key Channel-Metadaten in der ausgewählten App auflisten kann. Das automatische Child-Binding ist eine management boundary: es gewährt keine Lifecycle-Mutationen für Channels, die der Key nicht selbst erstellt hat.

Capgo protokolliert zudem, welcher App Preview Key ein Bundle hochgeladen hat. Der Key kann auf jedem von ihm erstellten Preview-Channel nur sein eigenes Bundle setzen und dieses Paar gemeinsam bereinigen. Er erhält keine Channel-Bindung für einen bestehenden Default- oder Main-Channel, einen von einem anderen Preview-Key erstellten Channel oder das Bundle eines anderen Keys.

Verwenden Sie für einen typischen CI-Job einen eindeutigen Channel-Namen pro Pull Request:

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --delete-bundle \
  --success-if-not-found

Für einen neuen Channel, bundle upload --channel erstellt den Channel, lädt das Bundle hoch und promotet es in einem Flow. Der letzte Befehl nutzt eine restriktive, atomare Cleanup-Route: Er ist nur erfolgreich, wenn der Key der Besitzer des Preview-Channels und des damit verknüpften, nicht geteilten Bundles ist. App-Vorschau hat immer noch keine allgemeinen bundle.delete, daher kann es kein beliebiges Bundle löschen.

Achtung

Verwende einen neuen, nicht öffentlichen pr-<number> Channel. Übergib keine --default, --self-assign, Rollout-Optionen oder --delete-linked-bundle-on-upload an diesen Workflow. Ein App-Vorschau Key kann keinen bestehenden Default-/Main-Channel, den Channel eines anderen Preview-Keys oder das Bundle eines anderen Keys promoten, löschen oder ändern. Das Widerrufen oder das Ablaufen des App-Bindings entfernt auch den effektiven Lifecycle-Zugriff des Keys.

Siehe den Access-Control-Referenz für die vollständige Grenze.

Wie verwalte (bearbeite) ich einen API Key?

Klicke auf das wrench icon Wähle (Verwalten) bei einem beliebigen RBAC-Key in der Liste aus. Dies öffnet die Detailseite des Keys, auf der du:

• Key ändern Namen.
• Aktualisiere die Organisationsrolle.
• Aktivieren oder deaktivieren Organisationen erstellen erlauben wenn der Key eine Admin-Organisationsrolle hat.
• Hinzufügen, entfernen oder ändern von App-spezifischen Rollen.

Klicken „Änderungen speichern“ wenn fertig.

Wie regeneriere ich einen API Key?

Um den Secret-Wert eines API Keys zu regenerieren, klicke auf das Refresh-Icon (Regenerate) bei einem beliebigen Key in der Liste.

Ein Bestätigungsdialog erscheint. Nach der Bestätigung:

• Für sichere (gehashte) Keys: Ein neuer Plain-Text-Key wird generiert und einmalig in einem Modal angezeigt. Kopiere ihn sofort.
• Für Plain-Text-Keys: Der Key-Wert wird serverseitig neu generiert.

Alle Integrationen, die den alten Key verwenden, werden sofort nicht mehr funktionieren.

Wie lösche ich einen API Key?

Klicke auf das Papierkorb-Icon (Löschen) bei einem beliebigen Key in der Liste. Bestätige die Löschung im Dialog.

Der Key wird sofort widerrufen – alle Anfragen mit diesem Key werden fehlschlagen.

Legacy-Keys

Wenn du Keys in der Alte Keys Sektion siehst (Keys ohne Rollenzuweisung), nutzen diese das ältere, auf Modi basierende Berechtigungssystem (read, upload, write, all). Sie funktionieren weiterhin, profitieren aber nicht von den feingranularen RBAC-Berechtigungen.

Legacy-Keys können aus der Liste regeneriert oder gelöscht werden, aber nicht bearbeitet werden, um RBAC-Rollen hinzuzufügen. Wir empfehlen, neue RBAC-Keys zu erstellen und Legacy-Keys nach Möglichkeit zu löschen.

Wenn du Legacy-Keys direkt verwalten musst, kannst du sie weiterhin unter console.capgo.app/dashboard/apikeysaufrufen. Diese Seite ist veraltet und wird in einem zukünftigen Update entfernt.

Weiter mit API Keys

Wenn du es nutzt API Schlüssel um Dashboard- und API-Operationen zu planen, verbinde es mit API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für die Implementierungsdetails in API Keys, Geräte für die Implementierungsdetails in Devices und Bundles für die Implementierungsdetails in Bundles.