API Clés

API est utilisé 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 optionnelle et peut être créée sous forme de « clé sécurisée » (hachée) où la valeur en clair n'est visible qu'une seule fois.

En utilisant 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/...

La authorization Le titre est également accepté mais est principalement destiné aux jetons JWT. Lorsque la valeur est une clé API formatée UUID, cela fonctionne, mais x-api-key est le titre recommandé pour tous les types de clés (y compris les clés sécurisées/hashtagées).

Permissions RBAC

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é sur 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 liens de rôle explicites, seuls ces liens de rôle sont évalués pour les vérifications d'autorisation. Les permissions personnelles du propriétaire de la clé ne sont pas héritées par la clé.

Note

Les clés sans liens de rôle retournent à un système basé sur des modes dépréciés (read, upload, write, all). Utilisez les rôles RBAC à la place.

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

La clé en clair

• 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 fois. Seule une hachage est stockée. Cela signifie : ne peut pas être récupéré après la création.
• La régénération produit une nouvelle clé au format texte (affichée une fois) et met à jour la hache stockée.
• Les clés hachées sont recommandées pour l'utilisation en production.

Certaines organisations imposent des clés hachées via la « politique de l'org ». enforce_hashed_api_keys Expiration

Sous-section intitulée « Expiration »

Les politiques d'organisation peuvent imposer :

Expiration obligatoire

• Toutes les nouvelles clés doivent avoir une date d'expiration. (require_apikey_expiration__CAPGO_KEEP_0__
• 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 Privilege MinimalAttribuez le rôle le plus restrictif qui permet toujours à votre intégration de fonctionner
2. Rotation RégulièreRotaitez vos API clés périodiquement en utilisant 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
4. Utilisation de Clés HachéesCréez des clés sécurisées (hachées) pour les intégrations de production
5. Fixer l'expiration: Fixez toujours une date d'expiration sur les clés utilisées pour un accès temporaire ou CI/CD
6. Restrictions d'Espace: Limitez les clés à des 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 déploiement: Utilisez des clés avec le app_developer rôle pour les scripts de déploiement 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 les 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 minimum requis