API Schlüssel
Kopiere einen Setup-Prompt mit den Installationsschritten und dem vollständigen Markdown-Guide für dieses Plugin.
API-Keys werden verwendet, um Anfragen an die Capgo API zu authentifizieren. Keys sind organisationsbezogen und können RBAC-Rollen zugewiesen werden, um den Zugriff fein granular zu steuern. Jeder Key kann zudem ein optionales Ablaufdatum haben und als „sicherer“ (gehashter) Key erstellt werden, bei dem der Klartextwert nur einmal angezeigt wird.
Einen API-Key verwenden
Abschnitt mit dem Titel „Einen API-Key verwenden“Nutze den im Endpoint dokumentierten Authentication-Header. Bei API-Key-Requests authorization wird akzeptiert:
curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...Einige Endpoints akzeptieren auch einen eigenen Key-Header. Der Kanäle API akzeptiert authorization oder capgkey; nutze einen dieser Header für die Preview-Channel-Automatisierung.
RBAC-Berechtigungen
Abschnitt mit dem Titel „RBAC-Berechtigungen“API-Keys nutzen dasselbe rollenbasierte Zugriffskontrollsystem (RBAC) wie Benutzerkonten. Beim Erstellen oder Verwalten von Keys über die Web-App oder API weisen Sie Rollen auf zwei Ebenen zu:
- Organisationsrolle — Definiert die Baseline-Berechtigungen des Keys für die gesamte Organisation (z. B.
org_adminoderorg_member). - App-Rollen — App-spezifische Berechtigungen (z. B.
app_admin,app_developer,app_uploader,app_reader, oderapp_preview).
Wenn ein API-Key explizite Rollenbindungen hat, nur diese Bindings werden für Berechtigungsprüfungen ausgewertet. Die persönlichen Berechtigungen des Key-Inhabers werden nicht auf den Key vererbt.
Preview-Channel-Automatisierung
Abschnitt „Preview-Channel-Automatisierung“Binden app_preview nur an die Preview-App für CI, die einen temporären, nicht öffentlichen Preview-Channel erstellt, ein Bundle hochlädt und promotet und dann beide löscht.
{ "name": "PR preview key", "hashed": true, "bindings": [ { "role_name": "app_preview", "scope_type": "app", "org_id": "<OWNING_ORG_UUID>", "app_id": "<APP_UUID>" } ]}org_id ist die UUID der Organisation, der die App gehört. app_id ist die interne UUID des App-Records, nicht die öffentliche App-Kennung, die von CLI-Befehlen verwendet wird (z. B. com.example.app). Die Bindung bleibt an die Organisation gebunden, selbst wenn der Key keine organisationsweite Rolle hat.
Auf App-Level app_preview umfasst die Rolle nur app.read, app.read_bundles, app.upload_bundle, und app.create_channel. Wenn dieser Schlüssel einen Channel erstellt, fügt Capgo automatisch eine channel_preview Binding auf dem neu erstellten Channel hinzu. Dieses Kind-Binding gewährt channel.read, channel.promote_bundle, und channel.delete nur für den Channel, den der Schlüssel erstellt hat.
app_preview behält app.read, daher ist dies keine strikte Channel-Lese-Isolation: Der Schlüssel kann Channel-Metadaten in der ausgewählten App auflisten. Das automatische Kind-Binding begrenzt Lifecycle-Änderungen auf den Channel, den der Schlüssel erstellt hat.
Capgo protokolliert den App-Preview-Schlüssel, der jedes Bundle hochgeladen hat. Der Schlüssel kann nur sein eigenes Bundle auf jeden Preview-Channel, den er erstellt, hochstufen. Er hat keinen Channel-Lifecycle-Zugriff auf einen bestehenden Default-/Main-Channel, einen Channel, der von einem anderen Preview-Schlüssel erstellt wurde, oder auf ein Bundle eines anderen Schlüssels. Für diesen Workflow weglassen public und niemals verwenden --default.
Nutzt channel delete <preview-channel> <public-app-id> --delete-bundle zur Bereinigung. Dies ist eine atomare Preview-Cleanup-Route mit Ownership-Check; sie entfernt nur den Preview-Channel und das verknüpfte Bundle des aufrufenden Keys. app_preview gewährt keine generischen bundle.delete.
Für das Dashboard-Setup und ein vollständiges CLI-Beispiel siehe Verwenden Sie einen App-Preview-Key für Preview-Workflows.

Berechtigung zur Organisationserstellung
Abschnitt „Berechtigung zur Organisationserstellung“Das Erstellen von Organisationen mit einem API-Key nutzt jetzt eine explizite globale Berechtigung: org.create.
Diese Berechtigung ist von normalen Org-/App-Rollenbindungen getrennt, da eine neue Organisation noch nicht existiert, wenn POST /organization/ der Aufruf erfolgt. Um Organisationen mit einem API-Key zu erstellen:
- Der API-Key muss Folgendes enthalten
org.createin einemglobal_permissions. - Derselbe API-Key muss außerdem eine aktuelle organisationsbezogene
org_adminoderorg_super_adminBindung haben. - Neue API-Keys erhalten standardmäßig nicht
org.createAktivieren Sie Organisationen erstellen erlauben beim Erstellen oder Bearbeiten eines RBAC-API-Keys im Dashboard. - Bestehende Org-Admin-/Super-Admin-API-Keys mit Schreibrechten wurden nachträglich mit
org.createdamit bestehende Integrationen weiterhin Organisationen erstellen können.
Wenn ein API-Key eine Organisation erstellt, weist Capgo automatisch denselben API-Key als org_super_admin der neu erstellten Organisation zu. So kann die Integration die gerade erstellte Organisation verwalten, ohne dass eine separate manuelle Rollenbindung erforderlich ist.
Wenn Sie einen API-Schlüssel über die API erstellen, fügen Sie global_permissions neben der Org-Admin-Bindung hinzu:
{ "name": "Provisioning key", "hashed": true, "bindings": [ { "role_name": "org_admin", "scope_type": "org", "org_id": "00000000-0000-0000-0000-000000000000" } ], "global_permissions": ["org.create"]}org.create gilt nur für das Erstellen von Organisationen. Zum Löschen einer Organisation ist weiterhin die Löschberechtigung für die Zielorganisation erforderlich, typischerweise über org_super_admin.
Sichere (gehashte) Keys
Abschnitt mit dem Titel „Sichere (gehashte) Schlüssel“Beim Erstellen eines sicheren Schlüssels generiert der Server das Schlüsselmaterial und gibt den Klartextwert nur einmal zurück. Es wird nur ein Hash gespeichert. Das bedeutet:
- Der Klartext-Schlüssel kann nicht abgerufen werden nach der Erstellung.
- Bei der Regenerierung wird ein neuer Klartext-Key (einmalig angezeigt) erzeugt und der gespeicherte Hash aktualisiert.
- Für den Produktiveinsatz werden gehashte Keys empfohlen.
Einige Organisationen erzwingen gehashte Keys über die enforce_hashed_api_keys Org-Policy.
Ablaufdatum
Abschnitt mit dem Titel „Ablauf“Keys können ein optionales Ablaufdatum haben. Abgelaufene Keys werden in der Berechtigungsprüfung abgelehnt.
Organisationsrichtlinien können durchsetzen:
- Verpflichtendes Ablaufdatum (
require_apikey_expiration) – Alle neuen Keys müssen ein Ablaufdatum haben. - Maximale TTL (
max_apikey_expiration_days) — Das Ablaufdatum darf nicht mehr als N Tage in der Zukunft liegen.
Sicherheits-Best-Practices
Abschnitt mit dem Titel „Security Best Practices“- Least-Privilege-Prinzip: Weise die restriktivste Rolle zu, die für deine Integration noch ausreicht
- Regelmäßige Rotation: Rotiere deine API Keys regelmäßig über die Regenerate-Funktion
- Sichere Speicherung: Speichere API Keys sicher und committe sie niemals in die Versionskontrolle
- Hashed Keys verwenden: Erstelle sichere (hashed) Keys für Produktionsintegrationen
- Ablaufdatum festlegen: Setze immer ein Ablaufdatum für Keys, die für temporären oder CI/CD-Zugriff genutzt werden
- Scope-Einschränkungen: Beschränke Keys auf spezifische Apps mit der minimal erforderlichen Rolle
Häufige Anwendungsfälle
Abschnitt mit dem Titel „Häufige Anwendungsfälle“- CI/CD-Integration: Erstellen Sie Schlüssel für bestimmte Apps mit der
app_uploaderoderapp_developerRolle und legen Sie ein Ablaufdatum fest. - PR-Preview-Channels: Nutze
app_previewnur auf die Preview-App oder Apps, wenn CI ein Bundle hochladen, einen temporären Channel erstellen und dessen eigenen Channel und Bundle atomar aufräumen muss. - Deployment-Automatisierung: Nutze Keys mit der
app_developerRolle für automatisierte Deployment-Skripte. - Monitoring-Tools: Erstelle Keys mit der
app_readerRolle für externe Monitoring-Integrationen. - Admin-Zugriff: Nutze Keys mit der
org_adminRolle sparsam für administrative Tools. - Drittanbieter-Integrationen: Erstelle auf spezifische Apps beschränkte Keys mit der minimal erforderlichen Rolle.
- Organisations-Provisioning: Nutze einen
org_adminoderorg_super_adminRBAC-Key mitorg.createnur für vertrauenswürdige Automatisierung, die Organisationen erstellen muss.
Weiter mit API Keys
Abschnitt mit dem Titel „Weiter mit API Keys“Wenn du es nutzt API Schlüssel Um Authentifizierungs- und Account-Flows zu planen, verbinde es mit @capgo/capacitor-social-login für die Implementierungsdetails in @capgo/capacitor-social-login, @capgo/capacitor-passkey für die Implementierungsdetails in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric für die Implementierungsdetails in @capgo/capacitor-native-biometric, Zwei-Faktor-Authentifizierung für die Implementierungsdetails zur Zwei-Faktor-Authentifizierung, und SSO (Enterprise) für die Implementierungsdetails zu SSO (Enterprise).