API Schlüssel

API Keys werden zur Authentifizierung von Anfragen an die Capgo API verwendet. Keys sind organisationsspezifisch und können mit RBAC-Rollen für eine feingranulare Zugriffskontrolle versehen werden. Jeder Key kann optional ein Ablaufdatum haben und als „sicherer“ (gehashter) Key erstellt werden, bei dem der Klartextwert nur einmal angezeigt wird.

Verwendung eines API Keys

Verwenden Sie den im Endpoint dokumentierten Authentication-Header. Für API Key-Anfragen authorization wird akzeptiert:

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

Einige Endpoints akzeptieren auch einen dedizierten Key-Header. Der Channels API akzeptiert authorization oder capgkey; nutzen Sie einen dieser Header für die Preview-Channel-Automatisierung.

RBAC-Berechtigungen

API Keys nutzen dasselbe RBAC-System (role-based access control) wie Benutzerkonten. Beim Erstellen oder Verwalten von Keys über die Web-App oder das API, werden Rollen auf zwei Ebenen zugewiesen:

• Organisationsrolle — Definiert die Basisberechtigungen des Keys für die gesamte Organisation (z. B. org_admin oder org_member).
• App-Rollen — App-spezifische Berechtigungen (z. B. app_admin, app_developer, app_uploader, app_reader, oder app_preview).

Wenn ein API Key explizite Role-Bindings hat, werden nur diese Bindings bei Permission-Checks berücksichtigt. Die persönlichen Berechtigungen des Key-Owners werden nicht auf den Key übertragen.

Channel-Automatisierung in der Vorschau

Bindet app_preview nur an die CI-Preview-App, die einen temporären, nicht öffentlichen Preview-Channel erstellt, ein Bundle hochlädt, promotet und anschließend 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-ID, die für CLI Befehle verwendet wird (z. B. com.example.app). Die Bindung bleibt an die Organisation gebunden, auch wenn der Key keine organisationsweite Rolle hat.

Die App-Ebene app_preview Rolle umfasst nur app.read, app.read_bundles, app.upload_bundle, und app.create_channel. Wenn dieser Key einen Channel erstellt, fügt Capgo automatisch eine channel_preview Bindung auf dem neu erstellten Channel hinzu. Diese Child-Bindung gewährt channel.read, channel.promote_bundle, und channel.delete nur für den Kanal, für den der Key erstellt wurde.

app_preview behält app.read, daher gibt es keine strikte Channel-Read-Isolation: Der Key kann Channel-Metadaten in der ausgewählten App auflisten. Die automatische Child-Bindung begrenzt Lifecycle-Mutationen auf den Kanal, für den der Key erstellt wurde.

Capgo protokolliert den App Preview Key, der jedes Bundle hochgeladen hat. Der Key kann nur sein eigenes Bundle in den jeweiligen Preview-Channel promoten, den er erstellt. Er hat keinen Zugriff auf den Lifecycle eines bestehenden Default/Main-Channels, eines von einem anderen Preview-Key erstellten Channels oder auf das Bundle eines anderen Keys. Lassen Sie für diesen Workflow diesen Teil weg public und verwenden Sie niemals --default.

Nutzt channel delete <preview-channel> <public-app-id> --delete-bundle zum Cleanup. Dies ist eine atomare, auf Ownership geprüfte Preview-Cleanup-Route; sie entfernt nur den Preview-Channel und das verknüpfte Bundle des aufrufenden Keys. app_preview gewährt keinen generellen bundle.delete.

Für das Dashboard-Setup und ein vollständiges CLI Beispiel, siehe Nutze einen App Preview Key für Preview-Workflows.

Hinweis

Keys ohne Role Bindings nutzen ein veraltetes, mode-basiertes System (read, upload, write, all). Diese Modes sind deprecated – nutze stattdessen RBAC Roles.

Berechtigung zur Organisation-Erstellung

Das Erstellen von Organisationen mit einem API Key nutzt nun eine explizite globale Permission: org.create.

Diese Permission ist von normalen Org/App Role Bindings getrennt, da noch keine neue Organisation existiert, wenn POST /organization/ aufgerufen wird. So erstellst du Organisationen mit einem API Key:

• Der API Key muss Folgendes enthalten: org.create in global_permissions.
• Derselbe API Key muss zudem eine aktuelle, organisationsweite org_admin oder org_super_admin Bindung haben.
• Neue API Keys erhalten org.create standardmäßig keine. Aktiviere Organisationen erstellen erlauben beim Erstellen oder Bearbeiten eines RBAC API Keys im Dashboard.
• Bestehende Schreibzugriff-fähige Org Admin/Super Admin API Keys wurden mit org.create nachgepflegt, damit bestehende Integrationen weiterhin Organisationen erstellen können.

Wenn ein API Key eine Organisation erstellt, weist Capgo denselben API Key automatisch org_super_admin für die neu erstellte Organisation zu. So kann die Integration die soeben erstellte Organisation verwalten, ohne dass ein manuelles Role Binding nötig ist.

Wenn du einen API Key über das API erstellst, füge ihn global_permissions zusammen mit 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 Orgs. Das Löschen einer Organisation erfordert weiterhin Delete-Berechtigungen für die Ziel-Organisation, meist über org_super_admin.

Sichere (gehashte) Keys

Beim Erstellen eines Secure Keys generiert der Server das Key-Material und gibt den Plain-Text-Wert nur einmal zurück. Es wird nur ein Hash gespeichert. Das bedeutet:

• Der Plain-Text Key kann nicht mehr abgerufen werden nach der Erstellung.
• Eine Regeneration erzeugt einen neuen Plain-Text Key (wird nur einmal angezeigt) und aktualisiert den gespeicherten Hash.
• Hashed Keys werden für den Production-Einsatz empfohlen.

Einige Organisationen erzwingen gehashte Keys über die enforce_hashed_api_keys Org-Policy.

Ablaufdatum

Keys können optional ein Ablaufdatum haben. Abgelaufene Keys werden beim Permission Check abgelehnt.

Organisation-Policies können Folgendes erzwingen:

• Pflicht-Ablaufdatum (require_apikey_expiration) — Alle neuen Keys müssen ein Ablaufdatum haben.
• Maximales TTL (max_apikey_expiration_days) — Das Ablaufdatum darf nicht weiter als N Tage in der Zukunft liegen.

Sicherheits-Best-Practices

1. Prinzip der minimalen Rechtevergabe: Weise die restriktivste Rolle zu, die für deine Integration noch ausreicht
2. Regelmäßige Rotation: Rotiere deine API Keys regelmäßig über die Regenerate-Funktion
3. Sichere Speicherung: Speichere API Keys sicher und committe sie niemals in die Version Control
4. Hashed Keys verwenden: Erstelle sichere (hashed) Keys für Production-Integrationen
5. Ablaufdatum festlegen: Setze immer ein Ablaufdatum für Keys, die für temporären oder CI/CD-Zugriff genutzt werden
6. Scope-Einschränkungen: Beschränke Keys auf spezifische Apps mit der minimal erforderlichen Rolle

Häufige Anwendungsfälle

1. CI/CD-Integration: Erstelle Keys für spezifische Apps mit der app_uploader oder app_developer Rolle und lege ein Ablaufdatum fest.
2. PR Preview Channels: Nutze app_preview nur auf der Preview-App (oder Apps), wenn die CI ein Bundle hochladen, einen temporären Channel erstellen und anschließend den eigenen Channel sowie das Bundle atomar bereinigen muss.
3. Deployment-Automatisierung: Nutze Keys mit der app_developer Rolle für automatisierte Deployment-Skripte.
4. Monitoring-Tools: Erstelle Keys mit der app_reader Rolle für externe Monitoring-Integrationen.
5. Admin-Zugriff: Nutze Keys mit der org_admin Rolle sparsam für Admin-Tools.
6. Drittanbieter-Integrationen: Erstelle Keys, die auf spezifische Apps mit der minimalen Rolle beschränkt sind.
7. Organisation-Provisionierung: Nutze einen org_admin oder org_super_admin RBAC-Key mit org.create nur für vertrauenswürdige Automatisierung, die Organisationen erstellen muss.

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).