Zum Inhalt springen

API Schlüssel

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.

Nutze den im Endpoint dokumentierten Authentication-Header. Bei API-Key-Requests authorization wird akzeptiert:

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

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_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 Rollenbindungen hat, nur diese Bindings werden für Berechtigungsprüfungen ausgewertet. Die persönlichen Berechtigungen des Key-Inhabers werden nicht auf den Key vererbt.

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.

Ein Diagramm, das erklärt, wie RBAC-API-Key-Berechtigungen funktionieren

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.create in einem global_permissions.
  • Derselbe API-Key muss außerdem eine aktuelle organisationsbezogene org_admin oder org_super_admin Bindung haben.
  • Neue API-Keys erhalten standardmäßig nicht org.create Aktivieren 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.create damit 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.

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.

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.
  1. Least-Privilege-Prinzip: 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 Versionskontrolle
  4. Hashed Keys verwenden: Erstelle sichere (hashed) Keys für Produktionsintegrationen
  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
  1. CI/CD-Integration: Erstellen Sie Schlüssel für bestimmte Apps mit der app_uploader oder app_developer Rolle und legen Sie ein Ablaufdatum fest.
  2. PR-Preview-Channels: Nutze app_preview nur 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.
  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 administrative Tools.
  6. Drittanbieter-Integrationen: Erstelle auf spezifische Apps beschränkte Keys mit der minimal erforderlichen Rolle.
  7. Organisations-Provisioning: Nutze einen org_admin oder org_super_admin RBAC-Key mit org.create nur für vertrauenswürdige Automatisierung, die Organisationen erstellen muss.

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