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

Mit einem API-Schlüssel arbeiten

Passen Sie Ihren API-Schlüssel in den x-api-key Kopf jeder Anforderung ein.

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

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

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 Rollen zuweisen, definieren Sie Rollen auf zwei Ebenen:

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

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

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.

Sichere (gehashte) Schlüssel

Bei der Erstellung eines sicheren Schlüssels generiert der Server das Schlüsselmaterial und gibt den plain-text-Wert einmal zurück. Nur ein Hash wird gespeichert. Das bedeutet:

• Der plain-text-Schlüssel kann nicht abgerufen werden nach der Erstellung.
• Die Regeneration erzeugt einen neuen, in Klartext stehenden Schlüssel (er wird einmal angezeigt) und aktualisiert den gespeicherten Hash.
• Für die Produktionsumgebung werden empfohlene gespeicherte Schlüssel verwendet.

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

Ablaufdatum

Schlüssel können ein optionales Ablaufdatum haben. Abgelaufene Schlüssel werden im Zugriffsprüfungsstapel abgelehnt.

Organisationsrichtlinien können Folgendes erzwingen:

• Pflichtablaufdatum (require_apikey_expiration— Alle neuen Schlüssel müssen einen Ablauftermin haben.
• Maximal TTL (max_apikey_expiration_days— Die Ablaufzeit kann 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 Hash-Schlüsseln: Erstellen Sie sichere (gehashte) Schlüssel für Produktionsintegrationen
5. Ablaufdatum setzen: Setze immer ein Ablaufdatum auf Schlüssel, die für temporäre oder CI/CD-Zugriffe verwendet werden
6. Bereichsbeschrä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 Rolle beschränkt sind und ein Ablaufdatum setzen
2. Automatisierte Bereitstellung: Verwende Schlüssel mit der app_developer Funktion für automatisierte Bereitstellungs-Skripte
3. Überwachungstools: Erstelle Schlüssel mit dem app_reader Funktion für externe Überwachungsinhalte
4. Administrator-Zugriff: Verwende Schlüssel mit dem org_admin Funktion sparsam für administrative Tools
5. Drittanbieter-Integrationen: Erstelle Schlüssel, die auf bestimmte Apps beschränkt sind, mit der minimal erforderlichen Funktion

Weiter geht es von API Schlüsseln

Wenn Sie __CAPGO_KEEP_0__ Schlüssel verwenden API Schlüssel um die Authentifizierung und die Kontenflüsse zu planen und 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).