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

Passen Sie Ihren API-Schlüssel in den x-api-key Anforderungsheader ein:

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

Der authorization Anforderungsheader wird auch akzeptiert, ist aber vor allem 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/gespeicherter 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-Basisrechte für 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 die 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 standardmäßig. Aktivieren Sie Erstellen von Organisationen zulassen bei der Erstellung oder Bearbeitung eines RBAC API-Schlüssels im Dashboard.
• Existierende schreibberechtigte Org-Admin/Super-Admin API-Schlüssel wurden mit org.create damit bestehende Integrations können weiterhin Organisationen 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 manuelles separates Rollenzuweisung zu verwalten.

Wenn Sie einen API-Schlüssel über den API erstellen, fügen 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 nur auf die Erstellung von Organisationen anwendbar. Die Löschung einer Organisation erfordert weiterhin die Löscherecht auf der Zielorganisation, typischerweise über org_super_admin.

Secure (Hashed) Keys

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.
• Gehashte Schlüssel werden für die Produktionsverwendung empfohlen.

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

Abgelaufen

Schlüssel können einen optionalen Ablaufdatum haben. Abgelaufene Schlüssel werden im Berechtigungsprüfungsstapel abgelehnt.

Unternehmensrichtlinien können Folgendes erzwingen:

• Pflichtende 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 dem Benutzer die am wenigsten privilegierten Rolle, die noch für die Funktion Ihres Integrationsdienstes erforderlich ist.
2. Regelmäßige Rotation: Regenerieren Sie Ihre API-Schlüssel regelmäßig mithilfe der Regenerationsfunktion
3. Sichere Speicherung: Speichere API-Schlüssel sicher und komme sie nie in die Versionskontrolle.
4. Verwende Hashed Keys: Erstelle sichere (gehashte) Schlüssel für Produktionsintegrationen.
5. Setz Ablaufdatum: Setze immer ein Ablaufdatum auf Schlüssel, die für temporäre oder CI/CD-Zugriffe verwendet werden.
6. Anwendungsbereichsbeschränkungen: Beschränke Schlüssel auf bestimmte Apps mit dem minimal erforderlichen Rolle.

Gemeinsame Anwendungsfälle

1. CI/CD-Integration: Erstelle Schlüssel, die auf bestimmte Apps mit dem app_uploader oder app_developer Funktion und Setzen einer Ablaufzeit
2. Automatisierte Bereitstellung: Verwende Schlüssel mit der app_developer Funktion für automatisierte Bereitstellungs-Skripte
3. Überwachungstools: Erstelle Schlüssel mit der app_reader Funktion für externe Überwachungs-Integrationen
4. Administratorzugriff: Verwende Schlüssel mit der org_admin Funktion sparsam für administrative Tools
5. Drittanbieter-Integrationen: Erstelle Schlüssel mit eingeschränktem Zugriff auf bestimmte Apps mit der minimal erforderlichen Funktion
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 für die Planung von Authentifizierung und Kontoflüssen verwenden, verbinden Sie ihn 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).