Clés API

Les clés API utilisent le contrôle d'accès basé sur les rôles (RBAC). Une clé peut avoir un rôl’à l'échelle de l'organisation, des liaisons limitées à une application, ou les deux. Chaque liaison d'application reste associée à l'organisation propriétaire de cette application. Pour respecter le principe du moindre privilège, limitez une clé à des applications sélectionnées plutôt que d'assigner un rôl’à l'échelle de l'organisation.

Où sont gérées les clés API ?

Accédez à Paramètres > Organisation > Clés API sur console.capgo.app/settings/organization/api-keys.

La page affiche deux sections :

• Clés RBAC — Clés avec rôles assignés (recommandé). Ces clés utilisent le nouveau système de permissions basé sur les rôles.
• Clés legacy — Les anciennes clés utilisant l'ancien système basé sur les modes («read, upload, write, all) sans rôl’assigné.

Comment créer une nouvelle clé API ?

1. Cliquez sur les ”+” bouton en haut du tableau des clés RBAC.

2. Remplissez les Informations sur la clé:

   • Nom (obligatoire) — Un libellé descriptif pour la clé (par exemple, « Déploiement CI/CD » ou « Monitoring en lecture seule »).
   • Créer une clé sécurisée (optionnel) — Si cette case est cochée, la clé est hachée côté serveur. La clé en clair ne s'affiche qu'une seule fois après la création et ne pourra pas être récupérée par la suite.
   • Définir une date d'expiration (optionnel) — Choisissez une date d'expiration pour la clé. Certaines organisations imposent une expiration via leurs politiques.

3. Choisissez la portée de la clé :

   • Accès à l'échelle de l'organisation — Sélectionnez un Rôle dans l'organisation pour définir les permissions de base de l'organisation. Les rôles disponibles dépendent de votre propre niveau de rôle :
     • Aucun — Aucun accès à l'échelle de l'organisation.
     • Membre — Accès en lecture seule à l'organisation.
     • Admin — Accès administratif complet à l'organisation et à toutes ses apps.
   • Accès limité aux apps — Activer Limiter cette clé aux apps sélectionnées. Chaque liaison d'app reste liée à l'organisation propriétaire de l'app ; ce mode omet uniquement le rôle RBAC au niveau de l'organisation.

4. Si la clé doit créer des organisations via l’API public, activez Autoriser la création d'organisations.

   Cela ajoute la permission org.create globale. La clé nécessite également une liaison org_admin ou org_super_admin liaison. Dans le dashboard, en sélectionnant Admin crée le org_admin lien. Lorsque cette clé crée une nouvelle organisation, Capgo attribue automatiquement la clé en tant que Super Admin à cette nouvelle organisation.

5. Pour accorder l'accès à une application :

   • Quand Limiter cette clé à des applications sélectionnées est activé, choisissez une organisation sous Organisations pour filtrer les applications pour afficher ses applications. Les liaisons d'applications sélectionnées restent associées à leurs organisations respectives ; ce filtre ne donne pas d'accès à l'ensemble de l'organisation.
   • Cliquez + Ajouter une app, sélectionnez une ou plusieurs applications, puis attribuez un rôl’à chacune :
     • Lecteur d'app — Accès en lecture seule à l'app.
     • Uploader d'app — Peut envoyer de nouveaux bundles.
     • Développeur d'app — Peut envoyer des bundles, gérer les appareils, lancer des builds natifs et modifier les paramètres des canaux.
     • Admin d'app — Accès complet à l'app.
     • Aperçu de l'app — Prévisualiser le cycle de vie CI/CD : envoyer un bundle et créer un canal de prévisualisation. Le canal reçoit des droits de cycle de vie automatiques, limités au canal, uniquement pour cette clé.

6. Cliquez « Créer ».

7. Si vous avez coché Créer une clé sécurisée, une modale affiche la clé en texte brut. Copiez-l’immédiatement — elle ne pourra pas être récupérée après la fermeture de la modale.

Utilisez une clé App Preview pour vos workflows de preview

Utiliser Aperçu de l'app pour la CI, qui crée un canal de preview temporaire et non public, envoie un bundle et le promeut, puis supprime le canal et le bundle. Elle n'a aucun accès au cycle de vie d'un canal par défaut ou principal existant.

1. Créer une clé RBAC et activer Limiter cette clé aux applications sélectionnées.
2. Inférieur à Organisations pour filtrer les apps, sélectionnez l'organisation pour afficher ses apps ; chaque app sélectionnée reste associée à son organisation propriétaire.
3. Ajoutez uniquement l'app ou les apps utilisées pour les déploiements de preview.
4. Sélectionnez Aperçu de l'app pour chaque app sélectionnée.
5. Créez une clé sécurisée, définissez une date d'expiration si nécessaire, et stockez-la dans votre gestionnaire de secrets CI.

Ce mode restreint l'accès aux seules applications sélectionnées ; il ne pas supprimer l'association avec l'organisation. Chaque app_preview liaison reste limitée à l'app sélectionnée et à l'organisation propriétaire de cette app.

Accorder	Permissions et périmètre
app_preview sur l'application sélectionnée	app.read, app.read_bundles, app.upload_bundle, et app.create_channel.
Automatique channel_preview liaison	Lorsque cette clé crée un canal, Capgo accorde automatiquement à la clé channel.read, channel.promote_bundle, et channel.delete uniquement pour ce canal.

app_preview conserve app.read, de sorte que la clé peut énumérer les métadonnées des canaux de l'application sélectionnée. La liaison enfant automatique est une gestion limite : la clé ne permet pas de modifier le cycle de vie des canaux qu'elle n'a pas créés.

Capgo enregistre également quelle clé App Preview a envoyé un bundle. La clé peut uniquement définir son propre bundle sur chaque canal de preview qu'elle crée et peut nettoyer cette paire conjointement. Elle ne reçoit pas de liaison de canal pour un canal par défaut ou principal existant, un canal créé par une autre clé de preview, ou le bundle d'une autre clé.

Pour un job CI classique, utilisez un nom de canal unique par pull request :

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --delete-bundle \
  --success-if-not-found

Pour un nouveau canal, bundle upload --channel crée le canal, envoie le bundle et le promeut en un seul flux. La dernière commande utilise une route de nettoyage atomique restreinte : elle ne réussit que si la clé possède le canal de preview et son bundle lié non partagé. Aperçu de l'app n'a toujours pas de permissions générales bundle.delete, elle ne peut donc pas supprimer un bundle arbitraire.

Attention

Utilisez un nouveau pr-<number> canal non public. Ne pas passer --default, --self-assign, les options de déploiement progressif, ou --delete-linked-bundle-on-upload à ce workflow. Une Aperçu de l'app clé ne peut pas promouvoir, supprimer ou modifier un canal par défaut/principal existant, le canal d'une autre clé de preview, ou le bundle d'une autre clé. La révocation ou l'expiration de la liaison de l'app supprime également l'accès au cycle de vie de la clé.

Consultez le Référence du contrôle d'accès pour l'ensemble des limites.

Comment gérer (modifier) une clé API ?

Cliquez sur les icône clé à molette (Gérer) sur n'importe quelle clé RBAC de la liste. Cela ouvre la page de détails de la clé où vous pouvez :

• Modifier le name.
• Mettez à jour le rôle de l'organisation.
• Activer ou désactiver Autoriser la création d'organisations lorsque la clé possède un rôl’Admin dans l'organisation.
• Ajouter, supprimer ou modifier les rôles par application.

Cliquez « Enregistrer les modifications » une fois terminé.

Comment régénérer une clé API ?

Pour régénérer la valeur secrète d'une clé API, cliquez sur icône de rafraîchissement (Régénérer) sur n'importe quelle clé de la liste.

Une boîte de dialogue de confirmation apparaît. Après confirmation :

• Pour clés sécurisées (hachées): une nouvelle clé en texte clair est générée et affichée une seule fois dans une modale. Copiez-l’immédiatement.
• Pour clés en clair : la valeur de la clé est régénérée côté serveur.

Toute intégration utilisant l'ancienne valeur de la clé cessera de fonctionner immédiatement.

Comment supprimer une clé API ?

Cliquez sur les icône de corbeille (Supprimer) sur n'importe quelle clé de la liste. Confirmez la suppression dans la boîte de dialogue.

La clé est révoquée immédiatement — toute requête l'utilisant échouera.

Clés héritées

Si vous voyez des clés dans la Clés legacy section (clés sans attribution de rôle), elles utilisent l'ancien système de permissions basé sur les modes (read, upload, write, all). Elles fonctionnent toujours mais ne bénéficient pas des permissions granulaires RBAC.

Les clés héritées peuvent être régénérées et supprimées depuis la liste, mais ne peuvent pas être modifiées pour ajouter des rôles RBAC. Nous recommandons de créer de nouvelles clés RBAC et de supprimer les clés héritées dès que possible.

Si vous devez gérer directement les clés héritées, vous pouvez toujours y accéder sur console.capgo.app/dashboard/apikeys. Cette page est obsolète et sera supprimée lors d'une future mise à jour.

Continuer avec les clés API

Si vous utilisez Clés API pour planifier les opérations du dashboard et de API, connectez-l’avec Aperçu de API pour les détails d'implémentation dans « Vue d'ensemble de API », Introduction pour les détails d'implémentation dans l'introduction, Clés API pour les détails d'implémentation dans API Keys, Appareils pour les détails d'implémentation dans Devices, et Les bundles pour les détails d'implémentation dans Bundles.