API Clés

API clés utilisent le contrôle d'accès basé sur le rôle (RBAC). Une clé peut avoir un rôl’organisationnel, des liens d'application, ou les deux. Chaque lien d'application reste associé à 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ôl’organisationnel.

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

Naviguer vers Paramètres > Organisation > Clés API à console.capgo.app/paramètres/organisation/api-clés.

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 permission basé sur les rôles.
• Clés Legacy — Anciennes clés qui utilisent le système de mode simple (read, upload, write, all) sans affectation de rôles.

Comment créer une nouvelle clé API ?

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

2. Remplissez le Informations clés:

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

3. Choisissez le champ d'application de la clé :

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

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

   Cela ajoute la clé d'API globale. org.create une permission. La clé nécessite également un organisation-étendu org_admin or org_super_admin Lier cette clé à l'application sélectionnée Admin crée les org_admin Lorsque cette clé crée une nouvelle organisation, Capgo attribue automatiquement la clé en tant que Super Administrateur 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 liens d'application sélectionnés restent associés à leurs organisations propriétaires ; ce filtre ne concède pas d'accès organisationnel.
   • Cliquez ”+ Add App”, sélectionnez une ou plusieurs applications, puis attribuez un rôl’à chacune :
     • App Reader — Accès en lecture seule à l'application.
     • Téléchargeur d'application — Peut télécharger de nouveaux ensembles.
     • Développeur d'application Pouvez télécharger des bundles, gérer les appareils, déclencher des builds natifs et configurer les paramètres de canal.
     • App Admin — Accès complet à l'application
     • App Preview — Prévisualisez le cycle CI/CD : téléchargez un bundle et créez un canal de prévisualisation. Le canal reçoit des droits de cycle automatique, uniquement pour ce canal, pour cette clé.

6. Cliquez “Créer”.

7. Si vous avez coché Créer une clé sécuriséeUne modal affiche la clé au format texte. Copiez-l’immédiatement Il ne peut pas être récupéré après la fermeture de la fenêtre modale.

Use an App Preview key for preview workflows

Utilisez App Preview pour les CI qui créent un canal de prévisualisation temporaire, non public, chargent et promeuvent un bundle, puis suppriment à 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éez une clé RBAC et activez Restreignez cette clé aux applications sélectionnées.
2. Sous Organisations pour filtrer les applicationsChoisissez l'organisation pour révéler ses applications ; chaque application sélectionnée reste associée à son organisation propriétaire.
3. Add only the app or apps used for preview deployments.
4. Sélectionner App Preview pour chaque application 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 sélection-apps-seul omet un rôl’organisationnel global ; il not supprimer l'association de l'organisation. Chaque app_preview La liaison reste scoping à son application sélectionnée et à l'organisation propriétaire de cette application.

Grant	sur chaque application sélectionnée.
app_preview ne supprime pas l'association organisationnelle.	app.read, app.read_bundles, app.upload_bundleet app.create_channel.
Automatique channel_preview liaison	Lorsque cette clé crée un canal, Capgo donne automatiquement la clé channel.read, channel.promote_bundleet channel.delete pour ce canal seulement.

app_preview retient app.read, donc la clé peut lister les métadonnées du canal dans l'application sélectionnée. La liaison automatique de l'enfant est une gestion La clé ne permet pas les mutations de cycle de vie pour les canaux qu'elle n'a pas créés.

Capgo enregistre également lequel de la clé d'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 une liaison de canal pour un canal par défaut ou principal existant, un canal créé par une autre clé de prévisualisation ou un 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é. App Preview n'a pas encore des fonctionnalités générales bundle.deletedonc elle ne peut pas supprimer un bundle arbitraire.

Attention

Utilisez une nouvelle clé d'API non publique pr-<number> options de déploiement, ou --default, --self-assignoptions de déploiement, ou --delete-linked-bundle-on-upload à ce flux de travail. Un App Preview Cette clé ne peut pas promouvoir, supprimer ou modifier un canal existant par défaut / principal, un autre canal de prévisualisation de clé ou un autre canal de clé. La révocation ou l'expiration de l'attachement de l'application supprime également l'accès à la durée de vie effective de la clé.

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

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

Cliquez sur Changer la clé Gérer n'importe quel clé RBAC de la liste. Cela ouvre la page détails de la clé où vous pouvez :

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

Cliquez sur « Enregistrer les modifications » lorsque terminé.

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

Régénérer la valeur secrète d'un API clé, cliquez sur icon de rafraîchissement (Régénérer) sur n'importe quelle clé de la liste.

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

• For clés sécurisées (hachées): Une nouvelle clé au format texte est générée et affichée une fois dans un modal. Copiez-l’immédiatement.
• For clés simples: La valeur de la clé est régénérée côté serveur.

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

Comment supprimer une clé API ?

Cliquez sur l' icône de poubelle (Supprimer) sur n'importe quelle clé de la liste. Confirmez la suppression dans le dialogue.

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

Clés Legacy

Si vous voyez des clés dans le Clés Héritées Ces clés utilisent le système de permission basé sur le mode plus ancien.read, upload, write, allElles fonctionnent toujours mais ne bénéficient pas des permissions RBAC détaillées.

Legacy keys can be regenerated and deleted from the list, but cannot be edited to add RBAC roles. We recommend creating new RBAC keys and deleting legacy keys when possible.

Si vous devez gérer des clés legacy directement, vous pouvez toujours y accéder à console.capgo.app/dashboard/clésAPI. Cette page est dépréciée et sera supprimée dans une mise à jour future.

Continuez avec les clés API

Si vous utilisez Clés API Pour planifier l'interface de bord et les API opérations, connectez-l’avec API Présentation pour le détail d'implémentation dans API Présentation Introduction pour le détail d'implémentation dans Introduction API Clés pour le détail d'implémentation dans API Clés Appareils pour le détail d'implémentation dans Appareils, et Ensembles pour le détail d'implémentation dans Ensembles.