Clés API

Les clés API utilisent un contrôle d'accès basé sur les rôles (RBAC). Une clé peut avoir un rôl’au niveau 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 le principe du moindre privilège, restreignez une clé à des applications sélectionnées plutôt que de lui attribuer un rôl’au niveau 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 (facultatif) — Choisissez une date après laquelle la clé ne fonctionnera plus. Certaines organisations imposent une expiration obligatoire via leur politique.

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

   • Accès à toute l’organisation — Sélectionnez un Rôle dans l'organisation pour définir les permissions de base dans toute l’organisation. Les rôles disponibles dépendent de votre propre niveau de rôle :
     • Aucun — Aucun accès à l’organisation.
     • Membre — Accès en lecture de base à l’organisation.
     • Admin — Accès administratif complet à l’organisation et à toutes ses applications.
   • Accès application uniquement — Activer Limiter cette clé aux applications sélectionnéesChaque liaison d’application reste associée à l’organisation propriétaire de l’application ; 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 globale org.create permission. La clé doit également être associée à une organisation org_admin ou org_super_admin binding. Dans le dashboard, sélectionner Admin crée le org_admin binding. Lorsque cette clé crée une nouvelle organisation, Capgo attribue automatiquement le rôle de Super Admin à cette clé sur la nouvelle organisation.

5. Pour accorder l’accès à une app :

   • Quand Limiter cette clé aux applications sélectionnées est activé, choisissez une organisation sous Organisations pour filtrer les apps pour afficher ses applications. Les liaisons d’applications sélectionnées restent associées à leurs organisations respectives ; ce filtre n’accorde 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 applications ; chaque application sélectionnée reste associée à son organisation d’origine.
3. Ajoutez uniquement les apps utilisées pour les déploiements de preview.
4. Sélectionnez Aperçu de l'app pour chaque application sélectionnée.
5. Créez une clé sécurisée, définissez une date d’expiration le cas échéant, et stockez-la dans votre gestionnaire de secrets CI.

Ce mode limité aux applications sélectionnées omet un rôl’au niveau de l’organisation ; il ne pas supprime pas l’association à l’organisation. Chaque app_preview le binding reste limité à l'application sélectionnée et à l'organisation qui en est propriétaire.

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 : elle n’accorde pas de mutations de cycle de vie pour les canaux que la clé n’a pas créés.

Capgo enregistre également quelle clé App Preview a uploadé un bundle. La clé ne peut définir que son propre bundle sur chaque canal de prévisualisation qu’elle crée et peut nettoyer cette paire ensemble. 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 prévisualisation, ou le bundle d’une autre clé.

Pour un job CI typique, 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, upload le bundle et le promeut en un seul flux. La dernière commande utilise une route de nettoyage atomique étroite : elle réussit uniquement si la clé possède le canal de prévisualisation et son bundle lié, non partagé. Aperçu de l'app n’a toujours pas de bundle.delete, il ne peut donc pas supprimer un bundle arbitraire.

Attention

Utilisez un nouveau pr-<number> canal non public. Ne transmettez pas --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/main existant, le canal d’une autre clé preview, ou le bundle d’une autre clé. La révocation ou l’expiration du binding de l’application supprime aussi l’accès effectif au cycle de vie de la clé.

Consultez le Référence du contrôle d'accès pour le périmètre complet.

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

Cliquez sur les wrench icon (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 la clé nom.
• Mettez à jour le rôle d’organisation.
• Activer ou désactiver Autoriser la création d'organisations lorsque la clé a un rôle d’organisation Admin.
• Ajouter, supprimer ou modifier rôles par app.

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 affectation de rôle), elles utilisent l’ancien système de permissions par mode (read, upload, write, all). Elles fonctionnent toujours, mais ne bénéficient pas des permissions granulaires RBAC.

Les clés legacy peuvent être régénérées et supprimées depuis la liste, mais il est impossible de les modifier pour y ajouter des rôles RBAC. Nous recommandons de créer de nouvelles clés RBAC et de supprimer les clés legacy lorsque c’est possible.

Si vous devez gérer directement des clés legacy, vous pouvez encore y accéder via console.capgo.app/dashboard/apikeys. Cette page est obsolète et sera supprimée dans 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.