API Clés

Les clés API sont utilisées pour authentifier les requêtes vers le Capgo API. Les clés sont spécifiques à l'organisation et peuvent être affectées de rôles RBAC pour un contrôle d'accès finement granulaire. Chaque clé peut également avoir une date d'expiration facultative et peut être créée sous forme de « clé sécurisée » (hachée) où la valeur en texte brut n'est visible qu'une seule fois.

Utilisation d'une clé API

Transmettez votre clé API dans l' x-api-key en-tête de chaque requête :

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

L' authorization en-tête est également accepté mais est principalement destiné aux jetons JWT. Lorsque la valeur est une clé API au format UUID, cela fonctionne, mais x-api-key est l'en-tête recommandée pour tous les types de clés (y compris les clés sécurisées/hachées).

Permissions RBAC

Les API clés utilisent le même système de contrôle d'accès basé sur les rôles (RBAC) que les comptes utilisateur. Lors de la création ou de la gestion de clés à travers l'application web, vous affectez des rôles à deux niveaux :

• Rôle d'organisation — Définit les permissions de base de la clé à travers l'ensemble de l'organisation (par exemple, org_admin, org_member).
• Rôles d'application — Permissions facultatives par application (par exemple, app_admin, app_developer, app_uploader, app_reader).

Si une clé API a des liaisons de rôle explicites, seules ces liaisons sont évaluées pour les vérifications de permission. Les permissions personnelles du propriétaire de la clé ne sont pas héritées par la clé.

Note

Les clés sans liaisons de rôle retournent à un système de mode basé sur la legacy (read, upload, write, allCes modes sont obsolètes — utilisez les rôles RBAC à la place.

Permission de création d'organisation

La création d'organisations avec une clé API utilise désormais une permission globale explicite : org.create.

Cette permission est séparée des liens de rôle normaux d'org/app car une nouvelle organisation n'existe pas encore lorsqu'elle est appelée. Pour créer des organisations avec une clé __CAPGO_KEEP_0__ : POST /organization/ La clé API doit inclure

• The API key must include org.create La même clé __CAPGO_KEEP_0__ doit également avoir un lien d'organisation actuel-scopé global_permissions.
• The same API key must also have a current organization-scoped org_admin Lors de la création de nouvelles clés __CAPGO_KEEP_0__, elles ne reçoivent pas org_super_admin Permission de création d'organisation
• Création d'organisations avec une clé API org.create par défaut. Activez Permettre la création d'organisations lors de la création ou de la modification d'une clé RBAC API dans le tableau de bord.
• Existing write-capable org admin/super admin API keys were backfilled with org.create afin que les intégrations existantes puissent continuer à créer des organisations.

Lorsqu'une clé API crée une organisation, Capgo attribue automatiquement la même clé API à org_super_admin dans l'organisation nouvellement créée. Cela permet à l'intégration de gérer l'organisation qu'elle vient de créer sans avoir besoin d'une liaison de rôle manuelle séparée.

Si vous créez une clé API à l'aide du API, incluez global_permissions en même temps que la liaison d'administrateur d'org :

{
  "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 ne s'applique qu'à la création d'organisations. La suppression d'une organisation nécessite toujours la permission de suppression sur l'organisation cible, généralement à travers org_super_admin.

Clés (hachées) sécurisées

Lors de la création d'une clé sécurisée, le serveur génère le matériau de clé et retourne la valeur en clair une seule fois. Seule une hachage est stockée. Cela signifie :

• La clé en clair ne peut pas être récupérée après la création.
• La régénération produit une nouvelle clé en clair (affichée une fois) et met à jour l'hachage stocké.
• Les clés hachées sont recommandées pour l'utilisation en production.

Certains organismes imposent des clés hachées via la enforce_hashed_api_keys politique de l'org.

Expiration

Les clés peuvent avoir une date d'expiration facultative. Les clés expirées sont rejetées au niveau de la vérification des permissions.

Les politiques d'organisation peuvent imposer :

• L'expiration obligatoire (require_apikey_expiration) — Toutes les nouvelles clés doivent avoir une date d'expiration.
• Durée de vie maximale (max_apikey_expiration_days) — La date d'expiration ne peut pas être plus éloignée de N jours.

Meilleures Pratiques de Sécurité

1. Principe de Moindre Privilège: Attribuez le rôle le plus restrictif qui permet toujours à votre intégration de fonctionner
2. Rotation Régulière: Rotornez vos API clés périodiquement à l'aide de la fonctionnalité de régénération
3. Stockage Sûr: Stockez les clés API de manière sécurisée et n'y commettez jamais de modifications de version
4. Utilisez des clés hachées: Créez des clés sécurisées (hachées) pour les intégrations de production
5. Expiration: Fixez toujours une date d'expiration sur les clés utilisées pour l'accès temporaire ou CI/CD
6. Restrictions d'Espace: Limitez les clés aux applications spécifiques avec le rôle requis minimum

Utilisations courantes

1. Intégration CI/CD: Créez des clés scoping spécifiques aux applications avec le app_uploader ou app_developer rôle et définir une date d'expiration
2. Automatisation de la mise en production: Utilisez des clés avec le app_developer rôle pour les scripts de mise en production automatisés
3. Outils de suivi: Créez des clés avec le app_reader rôle pour les intégrations de suivi externes
4. Accès administrateur: Utilisez des clés avec le org_admin rôle avec parcimonie pour les outils administratifs
5. Intégrations tierces: Créez des clés restreintes à des applications spécifiques avec le rôle requis minimum
6. Provisionnement d'organisationUtilisez un org_admin ou org_super_admin la clé RBAC avec org.create seulement pour l'automatisation fiable qui doit créer des organisations

Continuez de API Clés

Si vous utilisez API Clés pour planifier les flux d'authentification et de comptes, connectez-le avec @capgo/capacitor-connexion-social pour les détails d'implémentation dans @capgo/capacitor-connexion-social, pour la clé de passe @capgo/capacitor-passkey pour plus de détails sur l'implémentation dans @capgo/capacitor-passkey, pour la clé de passe native @capgo/capacitor-native-biometric pour plus de détails sur l'implémentation dans @capgo/capacitor-native-biometric, Authentification à deux facteurs pour plus de détails sur l'implémentation dans Authentification à deux facteurs, et SSO (Entreprise) pour plus de détails sur l'implémentation dans SSO (Entreprise).