API Clés

Les API clés utilisent le contrôle d'accès basé sur le rôle (RBAC). Une clé peut avoir un rôle organisationnel, des liens d'application, ou les deux. Chaque liaison d'application reste associée à l'organisation propriétaire de l'application. Pour le moins de privilèges, restreignez une clé à des applications sélectionnées au lieu d'attribuer un rôle organisationnel.

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

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

La page affiche deux sections :

• Clés RBAC — Clés avec des rôles attribués (recommandé). Ces clés utilisent le nouveau système de permission basé sur le rôle.
• Clés Legacy — Clés plus anciennes qui utilisent le système de mode simple (read, upload, write, allsans affectation de rôle.

Comment créer une nouvelle clé API ?

1. Cliquez sur le ”+” bouton en haut de la table des clés RBAC.

2. Remplissez les Informations de la clé:

   • Nom (obligatoire) — Un étiquette descriptive pour la clé (par exemple, « Déployer CI/CD » ou « Lecture seule de surveillance »).
   • Créer une clé sécurisée (facultatif) — Lorsque sélectionné, la clé est hachée côté serveur. La clé au texte brut est affichée seulement une fois après la création et ne peut pas être récupéré ultérieurement.
   • Définir la date d'expiration (facultatif) — Sélectionnez une date après laquelle la clé cesse de fonctionner. Certaines organisations imposent une expiration obligatoire par politique.

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

   • Accès organisationnel — Sélectionnez un rôle d'organisation pour définir les permissions de base au sein de l'organisation. Les rôles disponibles dépendent du niveau de votre propre rôle :
     • Aucun — Pas d'accès organisationnel.
     • Membre — Accès de lecture de base à l'organisation.
     • Administrateur — Accès administratif complet à l'organisation et à tous ses applications.
   • Accès uniquement par application — Activer Limitez cette clé aux applications sélectionnéesChaque liaison d'application reste liée à l'application qui en est propriétaire ; ce mode omet uniquement un rôle RBAC organisationnel.

4. Si la clé doit créer des organisations à travers le API public, activez Permettre la création d'organisations.

   Cela ajoute la permission globale. org.create La clé a également besoin d'une organisation-scoped org_admin ou org_super_admin liaison. Dans l'interface de dashboard, en sélectionnant Admin crée la org_admin liaison. Lorsque cette clé crée une nouvelle organisation, Capgo attribue automatiquement la clé en tant que Super Admin sur cette nouvelle organisation.

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

   • Lorsque Limitez cette clé aux applications sélectionnées est activé, choisissez une organisation sous Organisations pour filtrer les applications pour révéler ses applications. Les liaisons d'applications sélectionnées restent associées à leurs organisations propriétaires ; ce filtre ne concède pas l'accès organisationnel.
   • Cliquez Ajouter l'applicationSélectionnez une ou plusieurs applications, puis attribuez un rôle à chacune :
     • Lecteur d'application — Accès en lecture seule à l'application.
     • Téléchargeur d'application — Peut télécharger de nouveaux bundles.
     • Développeur d'application — Peut télécharger des bundles, gérer les appareils, déclencher des builds natifs et modifier les paramètres de canal.
     • Administrateur d'application — Accès complet à l'application.
     • Prévisualisation d'application — Prévisualisez le cycle de vie CI/CD : téléchargez un bundle et créez un canal de prévisualisation. Le canal reçoit des droits de cycle de vie automatiques, étendus uniquement au canal pour cette clé.

6. Cliquez « Créer ».

7. Si vous avez coché Créez une clé sécuriséeUne fenêtre contextuelle s'affiche avec la clé en texte brut. Copiez-la immédiatement — elle ne peut pas être récupérée après la fermeture de la fenêtre contextuelle.

Utilisez une clé d'App Preview pour les workflows de prévisualisation

Utilisez Clé d'App Preview pour CI qui crée un canal de prévisualisation temporaire et non public, envoie et promeut un bundle, puis supprime à la fois le canal et le bundle. Il n'a pas d'accès à la vie du cycle d'un canal par défaut ou principal existant.

1. Créer une clé RBAC et l'activer Limitez cette clé aux applications sélectionnées.
2. Sous Organisations pour filtrer les applications, sélectionnez l'organisation pour révéler ses applications ; chaque application sélectionnée reste associée à son organisation propriétaire.
3. Ajoutez uniquement les applications utilisées pour les déploiements de prévisualisation.
4. Sélectionner Prévisualisation d'application pour chaque application sélectionnée.
5. Créer une clé sécurisée, définir une date d'expiration lorsque cela est approprié, et la stocker dans votre gestionnaire de secrets CI.

Ce mode sélection-apps-omis omet un rôle organisationnel global ; il ne pas supprimer l'association de l'organisation. Chaque app_preview liaison reste scoping à son application sélectionnée et à celle-ci, propriétaire de l'organisation.

Accorder	Permissions et limites
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 donne automatiquement la clé channel.read, channel.promote_bundle, et channel.delete seulement pour ce canal.

app_preview retient app.read, afin que la clé puisse lister les métadonnées du canal sélectionné dans l'application. La liaison automatique de l'enfant est un gestion limites : elle ne concède pas les mutations de cycle de vie pour les canaux que la clé n'a pas créés.

Capgo enregistre également lequel de la clé App Preview a téléchargé un bundle. La clé peut définir uniquement son propre bundle sur chaque canal de prévisualisation qu'elle crée et peut nettoyer ce couple 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 demande de tirage :

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, télécharge le bundle et le promeut en un flux. La dernière commande utilise une route de nettoyage atomique étroite : elle réussit uniquement lorsque la clé possède le canal de prévisualisation et son bundle lié, non partagé. Prévisualisation d'application n'a toujours pas de général bundle.deleteAinsi, il ne peut pas supprimer un bundle arbitraire.

Attention

Utilisez un nouveau canal non public. pr-<number> Ne passez pas --default, --self-assign, les options de lancement, ou --delete-linked-bundle-on-upload à ce flux de travail. Un Prévisualisation d'application une clé ne peut pas promouvoir, supprimer ou modifier un canal existant par défaut/main, un canal d'une autre clé de prévisualisation, ou un bundle d'une autre clé. La révocation ou l'expiration de la liaison d'application supprime également l'accès au cycle de vie de la clé.

Consultez la Référence du Contrôle d'accès pour la limite complète.

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

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

• Changer le nom de la clé Mettre à jour le.
• rôle d'organisation Activer ou désactiver.
• Permettre la création d'organisations lorsque la clé a un rôle d'organisation Admin. Cliquez sur l'icône de la clé à molette
• Ajouter, supprimer ou modifier rôles par application.

Cliquez “Sauvegarder les modifications” une fois terminé.

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

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

Un dialogue de confirmation apparaîtra. Après confirmation :

• Pour les clés sécurisées (hachées) Une nouvelle clé au texte brut est générée et affichée une fois dans une fenêtre modale. Copiez-la immédiatement.Pour les clés au texte brut
• La valeur de la clé est régénérée côté serveur. Toute intégration utilisant la valeur de clé ancienne cessera de fonctionner immédiatement.Confirmation de régénération de la clé __CAPGO_KEEP_0__

Comment supprimer une clé __CAPGO_KEEP_0__ ?

How to delete an API key?

Pour les clés au texte brut : The key value is regenerated server-side. Any integration using the old key value will stop working immediately. Supprimer

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

Clés obsolètes

Si vous voyez des clés dans la Clés obsolètes section (clés sans affectations de rôle), celles-ci utilisent le système de permission basé sur le mode (read, upload, write, all). Elles fonctionnent toujours mais ne bénéficient pas des permissions RBAC détaillées.

Les clés obsolètes peuvent être régénérées et supprimées de la liste, mais ne peuvent pas être éditées pour ajouter des rôles RBAC. Nous recommandons de créer de nouvelles clés RBAC et de supprimer les clés obsolètes lorsque possible.

Si vous avez besoin de gérer les clés obsolètes directement, vous pouvez toujours les accéder à console.capgo.app/dashboard/apikeysCette page est dépréciée et sera supprimée dans une mise à jour future.

Continuez de API clés

Si vous utilisez API clés pour planifier le tableau de bord et les API opérations, connectez-le avec API Vue d'ensemble pour les détails d'implémentation dans API Vue d'ensemble, Introduction pour les détails d'implémentation dans Introduction, API clés pour les détails d'implémentation dans API clés, Appareils pour le détail d'implémentation dans Appareils, et Paquets pour le détail d'implémentation dans Paquets.