API Schlüssel

API-Schlüssel werden verwendet, um Anforderungen an den Capgo API zu authentifizieren. Schlüssel sind organisationsspezifisch und können Rollen für eine feinmaschige Zugriffssteuerung zugewiesen werden. Jeder Schlüssel kann auch eine optionale Ablaufzeit haben und kann als „sicher“ (gehashter) Schlüssel erstellt werden, wobei der plain-Text-Wert nur einmal angezeigt wird.

Verwendung eines API-Schlüssels

Verwenden Sie den in der Dokumentation des Endpunkts dokumentierten Authentifizierungsheader. Für API-Schlüssel-Anforderungen ist authorization Terminalfenster

curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

__CAPGO_KEEP_0__-Schlüssel Kanäle API akzeptiert authorization oder capgkeyVerwenden Sie einen dieser Header für die Automatisierung der Vorabkanal.

RBAC-Berechtigungen

API-Schlüssel verwenden das gleiche rollenbasierte Zugriffssteuerungssystem (RBAC) wie Benutzerkonten. Wenn Sie bei der Erstellung oder Verwaltung von Schlüsseln über die Webanwendung oder API Rollen zuweisen, definieren Sie sie auf zwei Ebenen:

• Organisationsrolle — Definiert die Berechtigungen des Schlüssels auf Ebene der gesamten Organisation (z. B. org_admin oder org_member).
• Anwendungsrollen — Per-Anwendungs-Berechtigungen (z. B. app_admin, app_developer, app_uploader, app_readeroder app_preview).

Wenn ein API-Schlüssel explizite Rollenzuweisungen hat, werden nur diese Zuweisungen für die Berechtigungsprüfungen ausgewertet. Die persönlichen Berechtigungen des Schlüsselbesitzers werden nicht durch den Schlüssel geerbt.

Vorschaukanalautomatisierung

Binden app_preview nur an die Vorschauanwendung für CI, die einen temporären, nicht öffentlichen Vorschaukanal erstellt, ein Paket hochlädt und promotet und beide dann 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, die die App besitzt. app_id ist die interne UUID des App-Records, nicht die öffentliche App-Identifikation, die von CLI-Befehlen verwendet wird (z. B. com.example.app) Die Bindung bleibt organisatorisch gebunden, auch wenn der Schlüssel keine organisatorischen Rollen hat.

Die App-Ebene app_preview enthält nur app.read, app.read_bundles, app.upload_bundle, und app.create_channel. Wenn diese Schlüssel eine Kanal erstellt, fügt Capgo automatisch eine channel_preview an dem neu erstellten Kanal. Diese untergeordnete Bindung gewährt channel.read, channel.promote_bundle, und channel.delete nur für den Kanal, den der Schlüssel erstellt hat.

app_preview behält app.read, so ist dies keine strikte Kanal-Leseisolation: Der Schlüssel kann die Kanal-Metadaten in der ausgewählten App auflisten. Die automatische untergeordnete Bindung beschränkt auf den Kanal, den der Schlüssel erstellt hat. __CAPGO_KEEP_0__ registriert den App-Vorschau-Schlüssel, der jeden Bundle hochgeladen hat. Der Schlüssel kann nur seinen eigenen Bundle in jeden Vorschau-Kanal hochladen, den er erstellt. Er hat keinen Zugriff auf das Lebenszyklus eines bestehenden Default/Main-Kanals, einen von einem anderen Vorschau-Schlüssel erstellten Kanal oder einen anderen Schlüssels Bundle. Für diesen Workflow sollte man

Capgo records the App Preview key that uploaded each bundle. The key can promote only its own bundle to each preview channel it creates. It has no channel lifecycle access to an existing default/main channel, a channel created by another preview key, or another key’s bundle. For this workflow, omit public und verwenden Sie sie nie --default.

Verwenden channel delete <preview-channel> <public-app-id> --delete-bundle zum Reinigen. Dies ist eine atomare, Eigentumsüberprüfungskontrollroute zum Vorabreinigen; sie entfernt nur den Aufrufschlüssel und das zugehörige Bundle. app_preview verleiht keine allgemeinen bundle.delete.

Für die Konfiguration des Dashboards und einen vollständigen CLI-Beispiel, sehen Sie Verwenden Sie einen App-Vorschau-Schlüssel für Vorab-Workflows.

Hinweis

Schlüssel ohne Rollenzuweisungen fallen auf ein veraltete Modus-basiertes System zurück (read, upload, write, allDiese Modi sind veraltet – verwenden Sie stattdessen RBAC-Rollen.

Organisationserstellungsrechte

Organisationen mit einem API-Schlüssel werden nun mit einer expliziten globalen Berechtigung erstellt: org.create.

Diese Berechtigung ist von normalen Org/App-Rollenbindungen getrennt, da eine neue Organisation noch nicht existiert, wenn POST /organization/ er aufgerufen wird. Um Organisationen mit einem API-Schlüssel zu erstellen:

• Der API-Schlüssel muss org.create enthalten global_permissions.
• Der gleiche API-Schlüssel muss auch eine aktuelle Organisation-gespeicherte org_admin oder org_super_admin HTML-Textfragment aus einem längeren Capgo-UI-String (Elternschlüssel `alternatives_cta_questions`). Seite/Bereich: Vergleichsseite für lebendige Capacitor-Updates. Rolle: Langes Marketing- oder Rechtsparagraph. Gesehen in: Seite alternatives.astro. Bewahre Capgo-Produkt- und -Markenbegriffe sowie Entwicklertitel genau. Nachrichtenschlüssel `alternatives_cta_questions` (Alternativen-CTA-Fragen). | HTML-Textfragment aus einem längeren Capgo-UI-String (Elternschlüssel `appflow_cta_questions`). Seite/Bereich: Appflow-Vergleichs- und -Migration-Marketing-Kopie. Rolle: Langes Marketing- oder Rechtsparagraph. Gesehen in: Seite ionic-appflow.astro. Bewahre Capgo-Produkt- und -Markenbegriffe sowie Entwicklertitel genau. Nachrichtenschlüssel `appflow_cta_questions` (Appflow-CTA-Fragen). | HTML-Textfragment aus einem längeren Capgo-UI-String (Elternschlüssel `capwesome_cta_questions`). Seite/Bereich: Capawesome-Vergleichsseite. Rolle: Langes Marketing- oder Rechtsparagraph. Gesehen in: Seite capwesome.astro. Bewahre Capgo-Produkt- und -Markenbegriffe sowie Entwicklertitel genau. Nachrichtenschlüssel `capwesome_cta_questions` (Capwesome-CTA-Fragen). | Seite/Bereich: Beratungsdienste-Seite. Rolle: Abschnittsunterschrift oder -Slogan. Gesehen in: Seite consulting.astro. Bewahre Capgo-Produkt- und -Markenbegriffe sowie Entwicklertitel genau. Nachrichtenschlüssel `consulting_faq_subtitle` (Beratungsdienste-Faq-Unterschrift). | Seite/Bereich: Appflow-Vergleichs- und -Migration-Marketing-Kopie. Rolle: Kurzer UI-Label oder Navigationselement. Gesehen in: Seite ionic-appflow.astro, Seite ionic-enterprise-plugins.astro, Seite solutions/ionic-enterprise-plugins.astro. Nachrichtenschlüssel `appflow_plugins_or` (Appflow-Plugins-oder)
• New API keys do not receive org.create Neue __CAPGO_KEEP_0__-Schlüssel erhalten standardmäßig nicht. Aktiviere ‘Organisationen erstellen lassen’ während der Erstellung oder Bearbeitung eines RBAC API-Schlüssels im Dashboard.
• Bestehende schreibgeschützte Organisationen-Admin/Super-Admin API-Schlüssel wurden mit org.create damit bestehende Integrationen weiterhin Organisationen erstellen können.

Wenn ein API-Schlüssel eine Organisation erstellt, Capgo übernimmt automatisch denselben API-Schlüssel als org_super_admin auf der neu erstellten Organisation. Dies ermöglicht es der Integration, die Organisation, die sie gerade erstellt hat, ohne manuelle Rolle-Zuweisung zu verwalten.

Wenn Sie einen API-Schlüssel über den API erstellen, fügen Sie global_permissions zusammen mit der Organisation-Admin-Zuweisung:

{
  "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 die Erstellung von Organisationen. Die Löschung einer Organisation erfordert weiterhin die Löschberechtigung auf der Zielorganisation, typischerweise über org_super_admin.

Sichere (gehaspte) Schlüssel

Bei der Erstellung eines sicheren Schlüssels generiert der Server das Schlüsselmaterial und gibt die Plain-Text-Wert einmal zurück. Nur ein Hash wird gespeichert. Das bedeutet:

• Der Textschlüssel kann nicht nach seiner Erstellung wiederhergestellt werden. wird nach der Erstellung nicht wiederhergestellt. wird nach der Erstellung nicht wiederhergestellt.
• Die Regeneration erzeugt einen neuen Textschlüssel (wird einmal angezeigt) und aktualisiert den gespeicherten Hash.
• Für die Produktionsnutzung werden empfohlen, verschlüsselte Schlüssel zu verwenden.

Einige Organisationen erzwingen verschlüsselte Schlüssel über die enforce_hashed_api_keys Ablaufdatum

Abschnitt mit dem Titel "Ablaufdatum"

Organisationsrichtlinien können erzwingen:

Pflichtmäßiges Ablaufdatum

• Mandatory expiration (require_apikey_expiration) — Alle neuen Schlüssel müssen eine Ablaufzeit haben.
• Maximale TTL (max_apikey_expiration_days) — Die Ablaufzeit darf nicht mehr als N Tage in der Zukunft liegen.

Sicherheitsbest Practices

1. Prinzip der geringsten Rechte: Zuweisen Sie dem restriktivsten Rollen, die immer noch Ihre Integration funktionieren lässt
2. Regelmäßige Rotation: Rotieren Sie Ihre API-Schlüssel regelmäßig mithilfe der Regenerationsfunktion
3. Sichere Speicherung: Speichern Sie API-Schlüssel sicher und committieren Sie sie nie in die Versionskontrolle
4. Verwendung von gehashten SchlüsselnErstellen Sie sichere (gehashte) Schlüssel für Produktionsintegrationen
5. Setzen Sie AblaufdatumSetzen Sie immer ein Ablaufdatum für Schlüssel, die für temporäre oder CI/CD-Zugriffe verwendet werden
6. Beschränkungen auf den BereichBeschränken Sie Schlüssel auf bestimmte Apps mit dem erforderlichen Mindestrolle

Gemeinsame Verwendungsfälle

1. CI/CD-IntegrationErstellen Sie Schlüssel, die auf bestimmte Apps mit dem app_uploader oder app_developer Beschränken Sie Schlüssel auf bestimmte Apps mit dem erforderlichen Mindestrolle und setzen Sie ein Ablaufdatum
2. PR-Vorschau-Kanäle: Verwenden app_preview nur auf der Vorschau-App oder -Apps, wenn CI eine Bundle hochladen, einen temporären Kanal erstellen und seinen eigenen Kanal und Bundle atomar bereinigen muss.
3. Automatisierte Bereitstellung: Verwenden Sie Schlüssel mit der app_developer Rolle für automatisierte Bereitstellungs-Skripte.
4. Überwachungstools: Erstellen Sie Schlüssel mit der app_reader Rolle für externe Überwachung-Integrations.
5. Administratorzugriff: Verwenden Sie Schlüssel mit der org_admin Rolle sparsam für administrative Tools.
6. Drittanbieter-Integrationen: Erstelle Schlüssel, die auf bestimmte Apps beschränkt sind und mit dem minimal erforderlichen Rolle erstellt werden.
7. Organisationszuteilung: Verwende einen org_admin oder org_super_admin Verwende einen Schlüssel, der nur für vertrauenswürdige Automatisierung verwendet wird, die Organisationen erstellen muss. org.create Weiter von __CAPGO_KEEP_0__ Schlüsseln

Abschnitt mit dem Titel "Weiter von API Schlüsseln"

App-Flows oder API Keys Schlüssel mit nur für vertrauenswürdige Automatisierung, die Organisationen erstellen muss. @capgo/capacitor-social-login zur Implementierungsdetail in @capgo/capacitor-social-login, @capgo/capacitor-passkey zur Implementierungsdetail in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric zur Implementierungsdetail in @capgo/capacitor-native-biometric, Zwei-Faktor-Authentifizierung zur Implementierungsdetail in Zwei-Faktor-Authentifizierung, und SSO (Unternehmen) zur Implementierungsdetail in SSO (Unternehmen).