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 fine-grain. 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 au texte brut n'est visible qu'une seule fois.

Utilisez 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/...

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

Permissions RBAC

Les clés API utilisent le même système de contrôle d'accès basé sur les rôles (RBAC) que les comptes utilisateur. Lorsque vous créez ou gérez des 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é pour 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 basé sur des modes dépréciés (read, upload, write, all)

Création de permission 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 normal 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 global_permissions.
• The same API key must also have a current organization-scoped org_admin de liaison. org_super_admin Les nouvelles clés __CAPGO_KEEP_0__ ne reçoivent pas
• New API keys do not receive org.create les Permettre la création d'organisations Lors de la création ou de la modification d'une clé RBAC API dans l'interface de dashboard.
• Les clés API administrateur/super administrateur d'organisation existantes ont été réapprovisionnées avec 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 sur 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 à travers le API, incluez global_permissions en même temps que la liaison d'administrateur d'organisation :

{
  "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

When vous créez 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é. 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.

Certaines organisations imposent des clés hachées via la enforce_hashed_api_keys politique de l'organisation.

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 :

• Expiration obligatoire (require_apikey_expiration) — Toutes les nouvelles clés doivent avoir une date d'expiration.
• TTL maximum (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: Régénérez vos API clés périodiquement à l'aide de la fonctionnalité de régénération
3. Stockage sécurisé: Stockez vos API clés de manière sécurisée et n'y commettez jamais de modifications dans le contrôle de version
4. Utilisez des clés chiffrées: Créez des clés sécurisées (chiffrées) pour les intégrations de production
5. Fixez une expiration: Fixez toujours une date d'expiration sur les clés utilisées pour l'accès temporaire ou CI/CD
6. Restrictions de portée: 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 fixez une date d'expiration
2. Automatisation de la Déploiement: Utilisez les clés avec le app_developer rôle pour les scripts de déploiement automatisés
3. Outils de Surveillance: Créez des clés avec le app_reader rôle pour les intégrations de surveillance externes
4. Accès Administrateur: Utilisez les clés avec le org_admin rôle avec parcimonie pour les outils administratifs
5. Intégrations de Tiers: Créez des clés restreintes à des applications spécifiques avec le rôle requis minimum
6. Provisionnement de l'Organisation: Utilisez un org_admin ou org_super_admin RBAC clé avec org.create seulement pour l'automatisation fiable qui doit créer des organisations

Continuez d'en API Clés

Si vous utilisez API Clés pour planifier l'authentification et les flux de compte, connectez-le avec @capgo/capacitor-social-login pour les détails d'implémentation dans @capgo/capacitor-social-login, @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey, @capgo/capacitor-native-biometric pour les détails d'implémentation dans @capgo/capacitor-native-biometric, L'authentification à deux facteurs pour les détails d'implémentation dans L'authentification à deux facteurs, et SSO (Entreprise) pour les détails d'implémentation dans SSO (Entreprise).