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 Ablaufdatum haben und als „sicher“ (gehashter) Schlüssel erstellt werden, wobei der Plain-Text-Wert nur einmal angezeigt wird.

Mit einem API-Schlüssel

Verwenden Sie den in der Dokumentation des Endpunkts dokumentierten Authentifizierungsheader. Für API-Schlüsselanforderungen ist authorization akzeptiert:

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

Einige Endpunkte akzeptieren auch einen dedizierten Schlüsselheader. Die API-Kanäle akzeptieren authorization oder capgkey; verwenden Sie einen dieser Kopfzeilen für die Automatisierung des 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, geschieht dies auf zwei Ebenen:

• Organisationsrolle — Definiert die Schlüssel-Basisberechtigungen über die gesamte Organisation (z.B. org_admin oder org_member).
• Anwendungsrollen — Per-Anwendungs-Berechtigungen (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 von der Schlüsselbesitzerrolle geerbt.

Vorschaukanal-Automatisierung

Binden app_preview nur an den Vorschau-App für CI, die eine temporäre, nicht öffentliche Vorschaukanal 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 App-Besitzerorganisation. app_id ist die interne UUID des App-Records, nicht der öffentlichen App-Bezeichner, der von CLI-Befehlen verwendet wird (z. B., com.example.app). Die Bindung bleibt auch dann organisationsspezifisch, wenn der Schlüssel keine organisationseinheitliche Rolle hat.

Die App-Rolle app_preview umfasst nur app.read, app.read_bundles, app.upload_bundle, und app.create_channel. Wenn sich der Schlüssel bei der Erstellung eines Kanals registriert, Capgo fügt automatisch eine channel_preview Verbindung auf den neu erstellten Kanal hinzu. Diese untergeordnete Verbindung 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, also handelt es sich nicht um eine strikte Kanal-Lese-Isolation: Der Schlüssel kann die Kanal-Metadaten in der ausgewählten App auflisten. Die automatisch erstellte untergeordnete Verbindung beschränkt Lebenszyklusmutationen auf den Kanal, den der Schlüssel erstellt hat.

Capgo dokumentiert den App-Vorschau-Schlüssel, der jedes Bundle hochgeladen hat. Der Schlüssel kann nur sein eigenes Bundle auf jeden von ihm erstellten Vorschaukanal vorziehen. Er hat keinen Zugriff auf den Lebenszyklus eines bestehenden Default/Main-Kanals, eines von einem anderen Vorschau-Schlüssel erstellten Kanals oder eines von einem anderen Schlüssel hochgeladenen Bundles. Für diesen Workflow sollten Sie public und sollten sie nie verwenden --default.

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

Für die Einrichtung 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, all). Diese Modi sind veraltet – verwenden Sie stattdessen RBAC-Rollen.

Organisationserstellungsberechtigung

Die Erstellung von Organisationen mit einem API-Schlüssel verwendet nun eine explizite globale Berechtigung: org.create.

Diese Berechtigung ist von normalen Organisation-/Anwendungsrolle-Zuweisungen getrennt, weil eine neue Organisation noch nicht existiert, wenn POST /organization/ 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 organisationsskalierte org_admin oder org_super_admin Zuweisung haben.
• Neue API-Schlüssel erhalten org.create durch Standard. Aktivieren Sie Ermöglichen Sie die Erstellung von Organisationen wenn Sie eine oder eine RBAC API-Schlüssel im Dashboard erstellen oder bearbeiten.
• Bestehende schreibfähige Organisation-Admin/Super-Admin API-Schlüssel wurden mit org.create So können bestehende Integrations die Organisationen weiterhin erstellen.

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 separate manuelle Rolenzuweisungen zu verwalten.

Wenn Sie einen API-Schlüssel über den API erstellen, sollten Sie global_permissions zusammen mit der Org-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 ist nur für die Erstellung von Organisationen relevant. Die Löschung einer Organisation erfordert weiterhin die Löschrechte auf die Zielorganisation, typischerweise über org_super_admin.

Sichere (gehaspte) Schlüssel

Wenn Sie einen sicheren Schlüssel erstellen, generiert der Server das Schlüsselmaterial und gibt die Klartextwerte einmal zurück. Nur ein Hash wird gespeichert. Das bedeutet:

• Der Klartextschlüssel liegt nicht wiederherstellbar nach der Erstellung.
• Die Regeneration erzeugt einen neuen Textschlüssel (einmal angezeigt) und aktualisiert den gespeicherten Hash.
• Für die Produktionsverwendung werden empfohlene Hashschlüssel.

Einige Organisationen erzwingen Hashschlüssel über die "org-Politik". enforce_hashed_api_keys Ablaufdatum

Abschnitt mit dem Titel "Ablaufdatum"

Organisationspolitiken können erzwingen:

Pflichtablaufdatum

• — Alle neuen Schlüssel müssen einen Ablaufdatum haben. (require_apikey_expirationMaximale TTL
• __CAPGO_KEEP_0__ (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 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 gehashten Schlüsseln: Erstellen Sie sichere (gehähte) Schlüssel für Produktionsintegrationen
5. Ablaufzeit setzen: Immer eine Ablaufzeit für Schlüssel setzen, die für temporäre oder CI/CD-Zugriffe verwendet werden
6. Zugriffsbeschränkungen: Schlüssel auf bestimmte Apps beschränken mit dem minimal erforderlichen Rolle

Umfangreiche Verwendungsfälle

1. CI/CD-Integration: Schlüssel auf bestimmte Apps beschränken mit dem app_uploader oder app_developer Rolle und eine Ablaufzeit setzen.
2. Vorschaukanäle für Pull-Requests: Verwenden Sie app_preview nur auf dem Vorschau-App oder Apps, wenn CI eine Bundle hochladen muss, einen temporären Kanal erstellen und seinen eigenen Kanal und Bundle atomisch bereinigen muss.
3. Automatisierte Bereitstellung: Verwende Schlüssel mit der app_developer Funktion für automatisierte Bereitstellungs-Skripte.
4. Überwachungsinstrumente: Erstelle Schlüssel mit der app_reader Funktion für externe Überwachungs-Integrationen.
5. Administratorzugriff: Verwende Schlüssel mit der org_admin Funktion sparsam für administrative Tools.
6. Drittanbieter-Integrationen: Erstelle Schlüssel eingeschränkt auf bestimmte Apps mit der minimal erforderlichen Funktion.
7. Organisationsbereitstellung: Verwenden Sie ein org_admin oder org_super_admin RBAC-Schlüssel mit org.create nur für vertrauenswürdige Automatisierung, die Organisationen erstellen muss.

Fortsetzen Sie von API Schlüsseln

Wenn Sie API Schlüsseln zur Planung der Authentifizierung und der Kontoflows verwenden, verbinden Sie es mit @capgo/capacitor-social-login zur Implementierungsdetail in @capgo/capacitor-social-login, @capgo/capacitor-passkey für die Implementierungsdetails in @capgo/capacitor-Passkey, @capgo/capacitor-native-Biometrie für die Implementierungsdetails in @capgo/capacitor-native-Biometrie, Zwei-Faktor-Authentifizierung für die Implementierungsdetails in Zwei-Faktor-Authentifizierung und SSO (Unternehmen) für die Implementierungsdetails in SSO (Unternehmen).