API Schlüssel

API-Schlüssel werden verwendet, um Anforderungen an den Capgo API zu authentifizieren. Die 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

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 Kopfzeile wird ebenfalls 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 die empfohlene Kopfzeile für alle Schlüsseltypen (einschließlich sicher/gespeister Schlüssel).

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, geschieht dies auf zwei Ebenen:

• Organisationsrolle — Definiert die Basisrechte der Schlüssel über die gesamte Organisation (z.B. org_admin, org_member).
• Anwendungsrollen — Optional pro-App-Rechte (z.B. app_admin, app_developer, app_uploader, app_reader).

Wenn ein API-Schlüssel explizite Rollenzuweisungen hat. nur diese Zuweisungen werden für Berechtigungsprüfungen ausgewertet. Die persönlichen Rechte 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.

Organisationserstellungsrechte

Die Erstellung von Organisations 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 Organisations 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 Neue __CAPGO_KEEP_0__-Schlüssel erhalten
• New API keys do not receive org.create Berechtigungen Erstellen von Organisationen zulassen bei der Erstellung oder Bearbeitung eines RBAC API-Schlüssels im Dashboard.
• Bestehende schreibgeschützte Org-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 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 manuelle Rolle-Zuweisung 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 trifft nur auf die Erstellung von Organisationen zu. Die Löschung einer Organisation erfordert weiterhin die Löscherecht auf der Zielorganisation, typischerweise über org_super_admin.

Secure (Hashed) Keys

When erstellt eine sichere Schlüssel, 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 Hashed Schlüssel für die Produktionsnutzung.

Einige Organisationen erzwingen Hashed Schlüssel über die enforce_hashed_api_keys org-Politik.

Abgelaufen

Schlüssel können eine optionale Ablaufdatum haben. Abgelaufene Schlüssel werden im Berechtigungsprüfungsstapel abgelehnt.

Organisationsrichtlinien können erzwingen:

• Pflichtige Ablaufdatum (require_apikey_expiration) — Alle neuen Schlüssel müssen eine Gültigkeit haben.
• Maximale TTL (max_apikey_expiration_days) — Die Gültigkeit darf nicht mehr als N Tage in der Zukunft 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 committieren Sie sie nie in die Versionskontrolle
4. Verwenden Sie Hashed Keys: Erstellen Sie sichere (gehashte) Schlüssel für Produktionsintegrationen
5. Setzen Sie Ablaufdatum: 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 beschränkt sind und ein Ablaufdatum setzen
2. Automatisierte Bereitstellung: Verwenden Sie Schlüssel mit der app_developer Rolle für automatisierte Bereitstellungs-Skripte
3. Überwachungstools: Erstellen Sie Schlüssel mit der app_reader Rolle für externe Überwachungs-Integrationen
4. Administratorzugriff: Verwenden Sie Schlüssel mit der org_admin Rolle sparsam für administrative Tools
5. Drittanbieter-Integrationen: Erstellen Sie Schlüssel mit der eingeschränkten Rolle für spezifische Apps
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

Bleiben Sie bei 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-biometrische für die Implementierungsdetails in @capgo/capacitor-native-biometrische Zweifaktor-Authentifizierung für die Implementierungsdetails in der Zweifaktor-Authentifizierung und SSO (Unternehmen) für die Implementierungsdetails in SSO (Unternehmen).