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ô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 privilégié, restreignez une clé à des applications sélectionnées au lieu d'attribuer un rôl’organisationnel.

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

Naviguez vers Paramètres > Organisation > Clés API à 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 — Les clés plus anciennes qui utilisent le système de mode simple (read, upload, write, all) sans affectation de rôle.

Comment créer une nouvelle clé API ?

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

2. Remplissez les Informations de clé:

   • 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 (facultatif) — Lorsque sélectionné, la clé est hachée côté serveur. La clé en texte brut est affichée seulement une fois après sa création et ne peut pas être récupérée 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 à grande échelle — 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 pour l'application — Activer Limitez cette clé aux applications sélectionnées. Chaque 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 public API, activer Permettre la création d'organisations.

   Cette fonction ajoute la permission globale. org.create La clé nécessite également une organisation scoping. org_admin ou org_super_admin La clé doit également être liée à une organisation. La clé doit être liée à une organisation. Lorsque vous créez une nouvelle organisation, __CAPGO_KEEP_0__ attribue automatiquement la clé en tant que Super Admin sur cette nouvelle organisation. org_admin binding. When this key creates a new organization, Capgo automatically assigns the key as Super Admin on that new organization.

5. Lorsque

   • Limitation de la clé aux applications sélectionnées est activée, choisissez une organisation sous Organisations pour filtrer les applications Permission 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 l'accès organisationnel.
   • Cliquez Ajouter l'application »Sélectionnez une ou plusieurs applications, puis attribuez un rôl’à chacune :
     • Lecteur d'application — Accès en lecture seule à l'application.
     • Téléchargeur d'application — Peut télécharger de nouveaux ensembles.
     • Développeur d'application — Peut télécharger des ensembles, gérer les appareils, déclencher des builds natifs et mettre à jour les paramètres de canal.
     • Administrateur d'application — Accès complet à l'application.
     • Aperçu d'application — 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 automatiques, uniquement pour ce canal.

6. Clicker « Créer ».

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

Utilisez une clé d'aperçu d'application pour les workflows de prévisualisation

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

1. Créez une clé RBAC et activez 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 l'application ou les applications utilisées pour les déploiements de prévisualisation.
4. Sélectionnez Prévisualisation d'application pour chaque application sélectionnée.
5. Créez une clé sécurisée, définissez une date d'expiration lorsque cela est approprié, et stockez-la dans votre gestionnaire de secrets de CI.

Cet mode sélection-apps-seul omite un rôl’organisationnel global ; il ne ne supprime pas l'association organisationnelle. Chaque app_preview liaison reste scoping à son application sélectionnée et à celle-ci propriétaire organisationnelle.

Accordez	Permissions et limites
app_preview sur l'application sélectionnée	app.read, app.read_bundles, app.upload_bundle, et app.create_channel.
liaison 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 uniquement.

app_preview conservent app.read, de sorte que la clé puisse énumérer les métadonnées du canal dans l'application sélectionnée. La liaison automatique d'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és de prévisualisation d'application 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 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 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 une seule opération. 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é. Aperçu de l'application n'a toujours pas de fonctionnalité générale bundle.deleteAinsi, il ne peut pas supprimer un bundle arbitraire.

Attention

Utilisez un nouveau canal non public. pr-<number> N'envoyez pas --default, --self-assign, options de déploiement, ou --delete-linked-bundle-on-upload à ce flux de travail. Un Aperçu de l'application clé ne peut pas promouvoir, supprimer ou modifier un canal existant par défaut/main, un autre canal de clé de prévisualisation ou un autre bundle de clé. La révocation ou l'expiration de la liaison de l'application supprime également l'accès à la durée de vie de la clé.

Consultez le Référence de Contrôle d'accès pour la frontière complète.

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

Cliquez sur l'icône de la clé à molette 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 de l'organisation Activer ou désactiver.
• 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 : Autoriser 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 » page d'édition de la clé __CAPGO_KEEP_0__ avec les paramètres de rôl’actuels

Section intitulée « Comment régénérer une clé API ? »

To regenerate the secret value of an API key, click the rôle d'organisation Admin (Réinitialiser) sur n'importe quelle clé de la liste.

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

• Pour clés (hachées) sécurisées: Une nouvelle clé au texte brut est générée et affichée une fois dans un modal. Copiez-l’immédiatement.
• Pour 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 la clé ancienne cessera de fonctionner immédiatement.

Comment supprimer une clé API ?

Appuyez sur l' icône de la 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 utilisant celle-ci échouera.

Clés Legacy

Si vous voyez des clés dans la Clés Legacy section (clés sans affectations de rôle), celles-ci 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 fines.

Les clés Legacy 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 Legacy lorsque possible.

Si vous devez gérer les clés légacieres directement, vous pouvez toujours y accéder à console.capgo.app/dashboard/apikeys. Cette page est obsolète et sera supprimée dans une mise à jour future.

Continuez de API Keys

Si vous utilisez API Keys pour planifier le tableau de bord et les opérations de API , connectez-l’à API Overview pour les détails d'implémentation dans API Overview, Introduction pour les détails 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.