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 fein abgestimmte 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 Authentifizierungsheader, der durch den Endpunkt dokumentiert ist. Für API-Schlüsselanfragen, authorization Terminalfenster

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

Einige Endpunkte akzeptieren auch einen dedizierten Schlüsselheader. Channels API an authorization or capgkeyVerwenden Sie einen dieser Header für die Vorab-Anzeige von Channel-Automatisierungen.

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, erfolgt dies auf zwei Ebenen:

• Organisationsrolle — Definiert die Schlüsselberechtigungen auf Ebene der gesamten Organisation (z. B. org_admin or org_member).
• Anwendungsrollen — Anwendungsrechte (z. B. app_admin, app_developer, app_uploader, app_reader, oder app_preview).

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

Vorschaukanal-Automatisierung

Binden app_preview nur an die Vorschauanwendung für CI, die einen temporären, nicht öffentlichen Vorschaukanal erstellt, ein Bundle 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, der das App gehört. app_id ist die interne UUID des App-Records, nicht die öffentliche App-Identifikator, der von CLI-Befehlen verwendet wird (z. B. com.example.appDie Bindung bleibt auch dann organisationsspezifisch, wenn der Schlüssel keine Organisationseinheit hat.

Die App-Ebene app_preview Einzelner Schlüssel app.read, app.read_bundles, app.upload_bundleund app.create_channel. Wenn diese Schlüssel eine Kanal erstellt, Capgo fügt automatisch eine channel_preview Verbindung auf dem neu erstellten Kanal hinzu. Diese untergeordnete Verbindung gewährt channel.read, channel.promote_bundleund channel.delete nur für den Kanal, den der Schlüssel erstellt hat.

app_preview behält app.read, daher handelt es sich nicht um eine strikte Kanal-Lese-Isolation: Der Schlüssel kann die Kanal-Metadaten in der ausgewählten App auflisten. Die automatische untergeordnete Verbindung beschränkt Lebenszyklusmutationen auf den Kanal, den der Schlüssel erstellt hat.

Capgo registriert den App-Vorschau-Schlüssel, der jede Bundle hochgeladen hat. Der Schlüssel kann nur sein eigenes Bundle in jeden Vorschau-Kanal hochladen, den er erstellt. Er hat keinen Zugriff auf den Lebenszyklus eines bestehenden Default/Main-Kanals, eines von einem anderen Vorschau-Schlüssel erstellten Kanals oder eines anderen Schlüssels Bundles. Für diesen Workflow sollten Sie public und verwenden sie nie --default.

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

Für die Konfiguration des Dashboards und einen vollständigen CLI-Beispiel, siehe Verwenden Sie einen App-Vorschau-Schlüssel für Vorschau-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.

Organisationserstellungsberechtigung

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

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

• Der API-Schlüssel muss org.create in global_permissions.
• Der gleiche API-Schlüssel muss auch eine aktuelle Organisation-gespeicherte org_admin oder org_super_admin oder
• Neue API-Schlüssel erhalten keine org.create Neue __CAPGO_KEEP_0__-Schlüssel erhalten durch Standard. Aktivieren Sie während der Erstellung oder Bearbeitung eines RBAC API-Schlüssels im Dashboard.
• wenn Sie eine RBAC API-Schlüssel in der Dashboard erstellen oder bearbeiten. org.create so bestehende Integrations können weiterhin Organisationen erstellen.

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

Wenn Sie einen API-Schlüssel über die API erstellen, fügen Sie global_permissions zusammen mit der Org-Admin-Bindung ein:

{
  "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öscherecht auf der Zielorganisation, typischerweise über org_super_admin.

Sichere (gehashte) Schlüssel

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

• Der plain-text-Schlüssel kann nicht wiederhergestellt werden nach der Erstellung.
• Regeneration erzeugt einen neuen Textschlüssel (angezeigt wird er einmal) und aktualisiert den gespeicherten Hash.
• Gesicherte Schlüssel werden für die Produktionsverwendung empfohlen.

Einige Organisationen erzwingen verschlüsselte Schlüssel über die enforce_hashed_api_keys org policy.

Ablaufdatum

Schlüssel können ein optionales Ablaufdatum haben. Abgelaufene Schlüssel werden im Zuge der Berechtigungsprüfung abgelehnt.

Organisationsrichtlinien können erzwingen:

• Pflichtablaufdatum (require_apikey_expirationAlle neuen Schlüssel müssen einen Ablaufdatum haben.
• Maximale TTL (max_apikey_expiration_days) — Die Gültigkeit kann nicht mehr als N Tage in der Zukunft liegen.

Sicherheitsbest Practices

1. Prinzip der geringsten Rechte: Zuweisen Sie die restriktivste Rolle, die noch Ihren Integrationsfunktion ermöglicht
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 Hash-Schlüsseln: Erstellen Sie sichere (gehashte) Schlüssel für Produktionsintegrationen
5. Ablaufdatum setzenSetze immer eine Ablaufzeit für Schlüssel, die für temporäre oder CI/CD-Zugriffe verwendet werden.
6. BereichsbeschränkungenBeschränke Schlüssel auf bestimmte Apps mit dem erforderlichen Mindestrolle.

Gemeinsame Verwendungsfälle

1. CI/CD-IntegrationErstelle Schlüssel, die auf bestimmte Apps mit dem app_uploader oder app_developer Rolle, und setzen Sie eine Ablaufzeit.
2. VorschaukanäleVerwende app_preview Uploade nur auf dem Vorschau-App oder -Apps, wenn CI eine Datei hochladen muss, erstelle einen temporären Kanal und lösche atomar seinen eigenen Kanal und die Datei.
3. Automatisierte BereitstellungVerwenden Sie Schlüssel mit dem app_developer Funktion für automatisierte Bereitstellungs-Skripte.
4. ÜberwachungstoolsAdministratorzugriff app_reader : Verwenden Sie die Rolle für administrative Tools sparsam.
5. DrittanbieterintegrationenVerwenden Sie Schlüssel mit dem org_admin role sparingly for administrative tools.
6. OrganisationsbereitstellungErstellen Sie Schlüssel, die auf bestimmte Apps beschränkt sind, mit dem minimal erforderlichen Rolle.
7. OrganisationsbereitstellungVerwende ein org_admin oder org_super_admin RBAC-Schlüssel mit org.create nur für vertrauenswürdige Automatisierung, die Organisationen erstellen muss.

Weiter mit API Schlüsseln

zur Implementierungsdetail in @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login, @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-passkey API Keys um Authentifizierung und Account-Flüsse zu planen, verbinden Sie es mit @capgo/capacitor-Social-Login für die Implementierungsdetails in @capgo/capacitor-Social-Login, @capgo/capacitor-Passwortschlüssel für die Implementierungsdetails in @capgo/capacitor-Passkey @capgo/capacitor-native-biometrisch für die Implementierungsdetails in @capgo/capacitor-native-biometrisch Zweifaktor-Authentifizierung für die Implementierungsdetails in Zweifaktor-Authentifizierung und SSO (Unternehmen) für die Implementierungsdetails in SSO (Unternehmen).