API Schlüssel

API-Schlüssel werden zur Authentifizierung von Anfragen an den Capgo API verwendet. Schlüssel sind organisationsspezifisch und können Rollen für 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.

Mit einem API-Schlüssel

Verwenden Sie den durch die Endpunkt dokumentierten Authentifizierungsheader. Für API-Schlüssel-Anfragen ist authorization Terminalfenster

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

Terminalfenster Kanäle API akzeptiert authorization oder capgkeyVerwenden Sie einen dieser Header für die Automatisierung der Vorabkanal-Übersicht.

RBAC-Berechtigungen

API-Schlüssel verwenden das gleiche rollenbasierte Zugriffssteuerungssystem 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 Schlüssel-Basisberechtigungen für die gesamte Organisation (z. B. org_admin oder org_member).
• App-Rollen — Per-App-Berechtigungen (z. B. app_admin, app_developer, app_uploader, app_reader, oder 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 das Vorschau-App für CI, das eine temporäre, nicht öffentliche 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 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.app). Die Bindung bleibt organisationsgebunden, selbst 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 Zuordnung auf den neu erstellten Kanal hinzu. Diese untergeordnete Zuordnung 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 ist dies keine strikte Kanal-Leseisolation: Der Schlüssel kann die Kanal-Metadaten in der ausgewählten App auflisten. Die automatische untergeordnete Zuordnung beschränkt Lebenszyklusmutationen auf den Kanal, den der Schlüssel erstellt hat.

Capgo registriert den App-Vorschau-Schlüssel, der jeden Bundle hochgeladen hat. Der Schlüssel kann nur seinen eigenen Bundle auf 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 sollten Sie public und verwenden Sie sie nie --default.

Verwenden channel delete <preview-channel> <public-app-id> --delete-bundle für die Reinigung. Dies ist eine atomare, Eigentumsüberprüfungsprüfungsroute für die Reinigung; sie entfernt nur den aufrufenden Schlüssels Vorschaukanal und das damit verbundene Bundle. app_preview erstellt nicht generische bundle.delete.

Für die Einrichtung des Dashboards und einen vollständigen CLI-Beispiel, sehen Sie sich bitte 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, allBerechtigung zur Organisationserstellung

Diese Modi sind veraltet – verwenden Sie stattdessen RBAC-Rollen.

Die Erstellung von Organisationen mit einem API-Schlüssel verwendet nun 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/ ist 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 Organisationsskala org_admin oder org_super_admin Die gleiche __CAPGO_KEEP_0__-Schlüssel muss auch eine aktuelle Organisationsskala
• New API keys do not receive org.create Die gleiche __CAPGO_KEEP_0__-Schlüssel muss auch eine aktuelle Organisationsskala oder während der Erstellung oder Bearbeitung eines RBAC API-Schlüssels im Dashboard.
• Bestehende schreibgeschützte Organisation-Admin/Überadmin-Schlüssel wurden mit API-Schlüsseln nachgefüllt. org.create So können bestehende Integrationsorganisationen weiterhin Organisationen erstellen.

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

Wenn Sie einen API-Schlüssel über den API erstellen, fügen Sie global_permissions zusammen mit der Organisation-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 (gehashpte) Schlüssel

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

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

Einige Organisationen erzwingen gesicherte Schlüssel über die enforce_hashed_api_keys Ablaufdatum

Abschnitt mit dem Titel „Ablaufdatum“

Organisationsrichtlinien können erzwingen:

Pflichtablaufdatum

• Section titled “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 integrierten System die restriktivste Rolle, die es noch immer ausführen lässt
2. Regelmäßige Rotation: Regenerieren Sie Ihre API-Schlüssel regelmäßig mithilfe der Regenerationsfunktion
3. Sichere Speicherung: Speichern Sie API-Schlüssel sicher und verpflichten Sie sie nie in die Versionskontrolle
4. Verwendung von gehashten Schlüsseln: Erstellen Sie sichere (gehashte) Schlüssel für Produktionsintegrationen
5. Ablaufdatum setzen: Setzen Sie immer ein Ablaufdatum für Schlüssel, die für temporäre oder CI/CD-Zugriffe verwendet werden
6. Bereichsbeschränkungen: Beschränken Sie Schlüssel auf bestimmte Apps mit dem minimal erforderlichen Rolle

Gemeinsame Anwendungsfälle

1. CI/CD-Integration: Erstellen Sie Schlüssel, die auf bestimmte Apps mit dem app_uploader oder app_developer Rolle und setzen Sie ein Ablaufdatum.
2. PR-Vorschau-Kanäle: Verwenden app_preview nur auf der Vorab-Anzeige oder -Anzeigen, 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. Überwachungsinstrumente: Erstellen Sie Schlüssel mit der app_reader Rolle für externe Überwachungsinhalte.
5. Administratorzugriff: Verwenden Sie Schlüssel mit der org_admin Rolle sparsam für administrative Werkzeuge.
6. Drittanbieterintegrationen: Erstelle Schlüssel, die auf bestimmte Apps beschränkt sind und die Mindestanforderungen erfüllen.
7. Organisationszuteilung: Verwende einen org_admin oder org_super_admin : Erstelle Schlüssel, die auf bestimmte Apps beschränkt sind und die Mindestanforderungen erfüllen. org.create : Verwende einen

Keep going from API Keys

: Verwende einen API Keys : Verwende einen @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 in Zwei-Faktor-Authentifizierung und SSO (Unternehmen) für die Implementierungsdetails in SSO (Unternehmen).