API Schlüssel

API-Schlüssel werden verwendet, um Anforderungen an das Capgo API zu authentifizieren. Schlüssel sind organisationsspezifisch und können RBAC-Rollen für eine fein granulierte 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

Fügen Sie Ihren API-Schlüssel in der x-api-key Anforderungskopfzeile ein:

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

Der authorization Anforderungskopfzeile wird auch akzeptiert, ist aber hauptsächlich für JWT-Tokens vorgesehen. Wenn der Wert ein UUID-formatiertes API-Schlüssel ist, funktioniert es, aber x-api-key ist der empfohlene Header für alle Schlüsseltypen (einschließlich sicher/gesicherter Schlüssel).

RBAC-Berechtigungen

API Schlüssel nutzen das gleiche rollenbasierte Zugriffssteuerungssystem (RBAC) wie Benutzerkonten. Wenn Sie Schlüssel über die Webanwendung erstellen oder verwalten, können Sie Rollen auf zwei Ebenen zuweisen:

• Organisationsrolle — Definiert die Schlüssel-Baseline-Berechtigungen über die gesamte Organisation (z.B. org_admin, org_member).
• Anwendungsrollen — Optional pro-Anwendungsberechtigungen (z.B. app_admin, app_developer, app_uploader, app_reader).

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

Hinweis

Schlüssel ohne Rollenzuweisungen fallen auf ein Legacy-Modus-System zurück (read, upload, write, allDiese Modi sind veraltet — verwenden Sie RBAC-Rollen stattdessen.

Organisationserstellungsberechtigung

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/ 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 Bindung haben.
• Neue API-Schlüssel erhalten keine org.create wenn Sie nicht aktiviert haben. Aktivieren Sie Möglichkeit zum Erstellen von Organisationen wenn Sie eine RBAC API-Schlüssel in der Oberfläche erstellen oder bearbeiten.
• Bestehende Schreibberechtigungen für Organisationen-Admin/Super-Admin API-Schlüssel wurden mit org.create damit bestehende Integrationen weiterhin Organisationen erstellen können.

Wenn ein API-Schlüssel eine Organisation erstellt, Capgo übernimmt automatisch die gleiche 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 Rolle-Zuweisung zu verwalten.

Wenn Sie einen API-Schlüssel über die API erstellen, fügen Sie global_permissions zusammen mit der Org-Admin-Zuweisung 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 das Erstellen von Organisationen. Die Löschung einer Organisation erfordert weiterhin die Löschberechtigung auf der Zielorganisation, typischerweise über org_super_admin.

Sichere (gehashte) Schlüssel

Wenn ein sicherer Schlüssel erstellt wird, generiert der Server das Schlüsselmaterial und gibt die Plain-Text-Wert einmal zurück. Nur ein Hash wird gespeichert. Das bedeutet:

• Der Plain-Text-Schlüssel kann nicht wiederhergestellt nach der Erstellung.
• Die Regeneration erzeugt einen neuen Plain-Text-Schlüssel (gezeigt einmal) und aktualisiert den gespeicherten Hash.
• Empfohlen werden geshachte Schlüssel für die Produktionsnutzung.

Einige Organisationen erzwingen geshachte Schlüssel über die enforce_hashed_api_keys Organisationsrichtlinie.

Ablaufdatum

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

Unternehmensrichtlinien können Folgendes erzwingen:

• Pflichtmäßige Ablaufzeit (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 Vergangenheit liegen.

Sicherheitsbest Practices

1. Prinzip der geringsten Rechte: Zuweisen Sie der Integration die restriktivste Rolle, die sie noch ausführen kann.
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 verpflichten Sie sich nie, sie in der Versionskontrolle zu committen
4. Verwenden Sie Hashed Keys: Erstellen Sie sichere (gehashte) Schlüssel für Produktionsintegrationen
5. Ablaufdatum setzen: Setzen Sie immer ein Ablaufdatum auf 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 eine Ablaufzeit
2. Automatisierte Bereitstellung: Verwenden Sie Schlüssel mit der app_developer Rolle für automatisierte Bereitstellungs-Skripte
3. Überwachungsinstrumente: Erstellen Sie Schlüssel mit der app_reader Rolle für externe Überwachungsinhalte
4. Administratorzugriff: Verwenden Sie Schlüssel mit der org_admin Rolle sparsam für administrative Werkzeuge
5. Drittanbieterintegrationen: Erstellen Sie Schlüssel mit der Rolle, die nur für bestimmte Apps erforderlich ist
6. Organisationsbereitstellung: Verwenden Sie einen org_admin oder org_super_admin RBAC-Schlüssel mit org.create nur für vertrauenswürdige Automatisierung, die Organisationen erstellen muss

Weitergehen von API Schlüsseln

Wenn Sie API Schlüssel zur Planung der Authentifizierung und der Kontoflows verwenden, verbinden Sie 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 in Zwei-Faktor-Authentifizierung und SSO (Unternehmen) für die Implementierungsdetails in SSO (Unternehmen).