Passer à la navigation
Capgo - Mises à jour en temps réel pour les applications Capacitor Capgo

API Clés

Les clés API sont utilisées pour authentifier les requêtes vers le Capgo API. Les clés sont spécifiques à l'organisation et peuvent être affectées de rôles RBAC pour un contrôle d'accès fine-grain. Chaque clé peut également avoir une date d'expiration optionnelle et peut être créée sous forme de « clé sécurisée » (hachée) où la valeur en texte brut n'est visible qu'une seule fois.

Utilisation d'une clé API

Section intitulée « Utilisation d'une clé API »

Utilisez l'en-tête d'authentification documentée par l'endpoint. Pour les requêtes de clé API-clé, authorization est accepté :

Fenêtre de terminal
curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

Certains endpoints acceptent également une en-tête de clé dédiée. Canaux API accepte authorization ou capgkey ; utilisez l'un de ces en-têtes pour l'automatisation de la chaîne de prévisualisation.

Permissions RBAC

Sous-section intitulée « Permissions RBAC »

Les clés API utilisent le même système de contrôle d'accès basé sur le rôle (RBAC) que les comptes utilisateur. Lors de la création ou de la gestion de clés à l'aide de l'application web ou de API, vous affectez des rôles à deux niveaux :

  • Rôle d'organisation — Définit les permissions de base de la clé au niveau de l'ensemble de l'organisation (par exemple, org_admin ou org_member).
  • Rôles d'application — Permissions par application (par exemple, app_admin, app_developer, app_uploader, app_readerL'option , ou app_preview).

Si une clé API a des liens de rôl’explicites, seuls ces liens sont évalués pour les vérifications d'autorisation. Les permissions personnelles du propriétaire de la clé ne sont pas héritées par la clé.

Automatisation du canal de prévisualisation

Section intitulée « Automatisation du canal de prévisualisation »

Se lier app_preview seul au canal de prévisualisation de l'application pour la CI qui crée un canal de prévisualisation temporaire et non public, envoie et promeut un bundle, puis supprime les deux.

{
  "name": "PR preview key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "app_preview",
      "scope_type": "app",
      "org_id": "<OWNING_ORG_UUID>",
      "app_id": "<APP_UUID>"
    }
  ]
}

org_id est l'UUID de l'organisation propriétaire de l'application. app_id est l'UUID interne du registre de l'application, et non l'identifiant public de l'application utilisé par les commandes CLI (par exemple, com.example.app. Le lien reste lié à l'organisation même lorsque la clé n'a pas de rôl’organisationnel.

L'appel d'application inclut uniquement app_preview et app.read, app.read_bundles, app.upload_bundle. Lorsque cette clé crée un canal, __CAPGO_KEEP_0__ ajoute automatiquement un app.create_channel. When that key creates a channel, Capgo automatically adds a channel_preview et channel.read, channel.promote_bundleseulement pour le canal que la clé a créé. channel.delete retient

app_preview , donc ce n'est pas une isolation stricte de lecture de canal : la clé peut lister les métadonnées de canal dans l'application sélectionnée. La liaison enfant automatique limite app.readmutations de cycle de vie à le canal que la clé a créé. __CAPGO_KEEP_0__ enregistre la clé de prévisualisation d'application qui a téléchargé chaque paquet. La clé peut promouvoir uniquement son propre paquet vers chaque canal de prévisualisation qu'elle crée. Elle n'a accès à aucun cycle de vie de canal pour un canal existant par défaut/main, un canal créé par une autre clé de prévisualisation ou un paquet d'une autre clé. Pour ce flux de travail, omettez

Capgo records the App Preview key that uploaded each bundle. The key can promote only its own bundle to each preview channel it creates. It has no channel lifecycle access to an existing default/main channel, a channel created by another preview key, or another key’s bundle. For this workflow, omit public et ne jamais utiliser --default.

Utilisez channel delete <preview-channel> <public-app-id> --delete-bundle pour la mise à jour. C'est une route de mise à jour atomique, vérifiant la propriété ; elle supprime uniquement le canal de prévisualisation et le bundle lié de la clé appelez. app_preview ne concède pas de droits génériques bundle.delete.

Pour la configuration du tableau de bord et un exemple complet de CLI, voir Utilisez une clé de prévisualisation d'application pour les workflows de prévisualisation.

Un diagramme expliquant comment les permissions de clé RBAC API fonctionnent

— utilisez les rôles RBAC à la place.

Section intitulée « Autorisation de création d'organisation »

La création d'organisations avec une clé API utilise désormais une permission globale explicite : org.create.

Cette permission est séparée des liens de rôle normal org/app car une nouvelle organisation n'existe pas encore lorsque POST /organization/ est appelée. Pour créer des organisations avec une clé API :

  • La clé API doit inclure org.create dans global_permissions.
  • La même clé API doit également avoir une organisation-scopée org_admin ou org_super_admin contexte : Fragment de texte HTML d'une chaîne de dialogue Capgo plus longue (clé parente `alternatives_cta_questions`). Page/zone : Comparaison de alternatives de mise à jour en direct de Capacitor. Rôle : Paragraphe de marketing ou juridique long. Vu dans : page alternatives.astro. Conservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `alternatives_cta_questions` (Questions de CTA Alternatives). | Fragment de texte HTML d'une chaîne de dialogue Capgo plus longue (clé parente `appflow_cta_questions`). Page/zone : Comparaison / migration de marketing de Appflow. Rôle : Paragraphe de marketing ou juridique long. Vu dans : page ionic-appflow.astro. Conservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `appflow_cta_questions` (Questions de CTA Appflow). | Fragment de texte HTML d'une chaîne de dialogue Capgo plus longue (clé parente `capwesome_cta_questions`). Page/zone : Page de comparaison de Capawesome. Rôle : Paragraphe de marketing ou juridique long. Vu dans : page capwesome.astro. Conservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `capwesome_cta_questions` (Questions de CTA Capawesome). | Fragment de texte HTML d'une chaîne de dialogue Capgo plus longue (clé parente `consulting_faq_subtitle`). Page/zone : Page de services de consulting. Rôle : Sujet de section ou tagline. Vu dans : page consulting.astro. Conservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `consulting_faq_subtitle` (Sujet de FAQ de consulting). | Page/zone : Comparaison / migration de marketing de Appflow. Rôle : Étiquette de navigation ou élément de navigation court. Vu dans : page ionic-appflow.astro, page ionic-enterprise-plugins.astro, page solutions/ionic-enterprise-plugins.astro. Clé de message `appflow_plugins_or` (Appflow Plugins Ou).
  • New API keys do not receive org.create Nouvelles clés __CAPGO_KEEP_0__ ne reçoivent pas par défaut. Activez : « Autoriser la création d'organisations » lors de la création ou de la modification d'une clé RBAC API dans le tableau de bord.
  • Les clés d'administrateur d'org existantes / administrateur super existantes API ont été réapprovisionnées avec org.create afin que les intégrations existantes puissent continuer à créer des organisations.

Lorsqu'une clé API crée une organisation, Capgo attribue automatiquement la même clé API à org_super_admin sur l'organisation nouvellement créée. Cela permet à l'intégration de gérer l'organisation qu'elle vient de créer sans avoir besoin d'une liaison de rôle manuelle séparée.

Si vous créez une clé API à travers l’API, incluez global_permissions en même temps que la liaison d'administrateur d'org :

{
  "name": "Provisioning key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "org_admin",
      "scope_type": "org",
      "org_id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "global_permissions": ["org.create"]
}

org.create ne s'applique qu'à la création d'organisations. La suppression d'une organisation nécessite toujours la permission de suppression sur l'organisation cible, généralement à travers org_super_admin.

Clés sécurisées (hachées)

Titre de la section « Clés sécurisées (hachées) »

Lors de la création d'une clé sécurisée, le serveur génère le matériau de clé et retourne la valeur en clair une seule fois. Seule une hachage est stockée. Cela signifie :

  • La clé au format texte ne peut pas être récupérée après sa création.
  • La régénération produit une nouvelle clé au format texte (affichée une fois) et met à jour la hache stockée.
  • Les clés hachées sont recommandées pour l'utilisation en production.

Certains organismes imposent des clés hachées via la enforce_hashed_api_keys politique de l'org.

Expiration

Sous-section intitulée « Expiration »

Les clés peuvent avoir une date d'expiration facultative. Les clés expirées sont rejetées au niveau de la vérification des permissions.

Les politiques d'organisation peuvent imposer :

  • L'expiration obligatoire (require_apikey_expiration) — Toutes les nouvelles clés doivent avoir une date d'expiration.
  • Maximum TTL (max_apikey_expiration_days) — La date d'expiration ne peut pas être plus éloignée de N jours.

Meilleures Pratiques de Sécurité

Section intitulée « Meilleures Pratiques de Sécurité »
  1. Principe de Moindre Privilège: Attribuez le rôle le plus restrictif qui permet toujours à votre intégration de fonctionner
  2. Rotation Régulière: Régénérez vos API clés périodiquement à l'aide de la fonctionnalité de régénération
  3. Stockage Sécurisé: Stockez vos API clés de manière sécurisée et n'y commettez jamais de modifications dans le contrôle de version
  4. Utilisation de Clés HachéesCréer des clés sécurisées (hachées) pour les intégrations de production
  5. Fixer l'expirationCréer toujours une date d'expiration pour les clés utilisées pour l'accès temporaire ou CI/CD
  6. Restrictions de portéeCréer des clés scoping spécifiques aux applications avec le rôle requis minimum

Utilisations courantes

Intégration CI/CD
  1. Créer des clés scoping spécifiques aux applications avec leou app_uploader PR Preview Channels app_developer Créer des clés scoping spécifiques aux applications avec le rôle requis minimum et fixer une date d'expiration
  2. Créer des clés scoping spécifiques aux applications avec le rôle requis minimum et fixer une date d'expiration: Utilisez app_preview sur l'application de prévisualisation ou les applications uniquement lorsque CI doit télécharger un bundle, créer un canal temporaire et nettoyer atomiquement son propre canal et bundle.
  3. Automatisation de la Déploiement: Utilisez les clés avec le app_developer rôle pour les scripts de déploiement automatisés.
  4. Outils de Suivi: Créez des clés avec le app_reader rôle pour les intégrations de suivi externes.
  5. Accès Administratif: Utilisez les clés avec le org_admin rôl’avec parcimonie pour les outils administratifs.
  6. Intégrations de TiersCréez des clés restreintes à des applications spécifiques avec le rôle requis minimum.
  7. Provisionnement de l'organisationUtilisez un org_admin ou org_super_admin Alternatives : Comment choisir entre nos solutions ? org.create ou

Keep going from API Keys

Section titled “Keep going from API Keys”

Sous-titre de la section : Continuez d'ici : Clés API Keys pour planifier l'authentification et les flux de compte, connectez-l’avec @capgo/capacitor-social-login pour les détails d'implémentation dans @capgo/capacitor-login-social, @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey, @capgo/capacitor-authiométrique-natif pour les détails d'implémentation dans @capgo/capacitor-authiométrique-natif, La deuxième facteur d'authentification pour les détails d'implémentation dans La deuxième facteur d'authentification, et L'authentification unique (Entreprise) pour les détails d'implémentation dans L'authentification unique (Entreprise).