Clés API

Les clés API servent à authentifier les requêtes adressées à l'API Capgo. Les clés sont propres à l'organisation et peuvent être associées à des rôles RBAC pour un contrôle d'accès granulaire. Chaque clé peut aussi avoir une date d'expiration facultative et être créée en clé « sécurisée » (hachée), dont la valeur en clair n'est affichée qu'une seule fois.

Utiliser une clé API

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

curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

Certains endpoints acceptent également un en-tête de clé dédié. Le Canaux API accepte authorization ou capgkey; utilisez l'un de ces en-têtes pour l'automatisation des canaux de prévisualisation.

Permissions RBAC

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

• Rôle dans l'organisation — Définit les permissions de base de la clé pour toute l'organisation (par exemple, org_admin ou org_member).
• Rôles de l'app — Permissions par application (par exemple, app_admin, app_developer, app_uploader, app_reader, ou app_preview).

Si une clé API possède des liaisons de rôles explicites, seules ces liaisons sont évaluées pour les vérifications de permissions. La clé n'hérite pas des permissions personnelles de son propriétaire.

Automatisation des canaux de preview

Lier app_preview uniquement à l'application de preview pour la CI qui crée un canal de preview temporaire et non public, effectue l'upload et la promotion d'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 de l'enregistrement de l'application, et non l'identifiant public utilisé par les commandes CLI (par exemple, com.example.app). La liaison reste liée à l'organisation, même si la clé n'a aucun rôl’au niveau de l'organisation.

Au niveau de l'application app_preview le rôl’inclut uniquement app.read, app.read_bundles, app.upload_bundle, et app.create_channel. Lorsque cette clé crée un canal, Capgo ajoute automatiquement une channel_preview liaison sur le canal nouvellement créé. Cette liaison enfant accorde channel.read, channel.promote_bundle, et channel.delete uniquement pour le canal créé par la clé.

app_preview conserve app.read, il ne s'agit donc pas d'une isolation stricte par canal : la clé peut énumérer les métadonnées des canaux de l'application sélectionnée. La liaison automatique des enfants limite mutations de cycle de vie au canal créé par la clé.

Capgo enregistre la clé App Preview qui a effectué l'upload de chaque bundle. La clé peut uniquement promouvoir son propre bundle vers chaque canal de preview qu'elle crée. Elle n'a aucun accès au cycle de vie d'un canal par défaut/principal existant, d'un canal créé par une autre clé de preview, ni au bundle d'une autre clé. Pour ce workflow, omettez public et n'utilisez jamais --default.

Utiliser channel delete <preview-channel> <public-app-id> --delete-bundle pour le nettoyage. Il s'agit d'une route de nettoyage de preview atomique avec vérification de propriété ; elle supprime uniquement le canal de preview et le bundle lié à la clé appelante. app_preview ne donne pas d'accès générique bundle.delete.

Pour la configuration du dashboard et un exemple complet de CLI, consultez Utilisez une clé App Preview pour vos workflows de preview.

Remarque

Les clés sans liaison de rôl’utilisent un système hérité basé sur les modes (read, upload, write, all). Ces modes sont obsolètes — utilisez plutôt les rôles RBAC.

Permission 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 distincte des liaisons de rôles org/app classiques, car une nouvelle organisation n'existe pas encore lorsque POST /organization/ est appelé. 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 disposer d'un org_admin ou org_super_admin liaison.
• Les nouvelles clés API ne reçoivent pas org.create 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 dashboard.
• Les clés API existantes (admin/super admin d'organisation avec droits d'écriture) ont été complétées avec org.create pour que les intégrations existantes puissent continuer à créer des organisations.

Lorsqu'une clé API crée une organisation, Capgo assigne automatiquement cette même clé API en tant que org_super_admin sur l'organisation nouvellement créée. L'intégration peut ainsi gérer l'organisation qu'elle vient de créer sans avoir besoin d'un binding de rôle manuel séparé.

Si vous créez une clé API via l’API, incluez global_permissions avec la liaison admin de l'organisation :

{
  "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 s'applique uniquement à la création d'organisations. La suppression d'une organisation nécessite toujours la permission de suppression sur l'organisation cible, généralement via org_super_admin.

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

Lors de la création d'une clé sécurisée, le serveur génère la clé et renvoie sa valeur en clair une seule fois. Seul un hash est stocké. Cela signifie :

• La clé en clair ne peut pas être récupérée après sa création.
• La régénération produit une nouvelle clé en clair (affichée une seule fois) et met à jour le hash stocké.
• L'utilisation de clés hachées est recommandée pour la production.

Certaines organisations imposent des clés hachées via la enforce_hashed_api_keys org policy.

Expiration

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

Les politiques de l'organisation peuvent imposer :

• Expiration obligatoire (require_apikey_expiration) — All new keys must have an expiry.
• TTL maximum (max_apikey_expiration_days) — L'expiration ne peut pas dépasser N jours à partir d'aujourd'hui.

Bonnes pratiques de sécurité

1. Principe du moindre privilège: Attribuez le rôle le plus restrictif permettant à votre intégration de fonctionner
2. Rotation régulière: Faites tourner vos clés API périodiquement via la fonction de régénération
3. Stockage sécuriséStockez vos clés API en toute sécurité et ne les commitez jamais dans votre version control
4. Utilisez des clés hachées: Créez des clés sécurisées (hachées) pour vos intégrations en production
5. Définissez une expiration: Définissez toujours une date d'expiration pour les clés utilisées pour un accès temporaire ou CI/CD
6. Restrictions de portée: Limitez les clés à des apps spécifiques avec le rôle minimum requis

Cas d'usage courants

1. Intégration CI/CD: Créez des clés limitées à des apps spécifiques avec le app_uploader ou app_developer rôle, et définissez une date d'expiration.
2. Canaux de preview PR : Utilisez app_preview uniquement sur l'app ou les apps de preview lorsque la CI doit envoyer un bundle, créer un canal temporaire, et nettoyer de manière atomique son propre canal et bundle.
3. Automatisation du déploiement : Utilisez les clés avec le app_developer rôle pour les scripts de déploiement automatisés.
4. Outils de monitoring : Créez des clés avec le app_reader rôle pour les intégrations de monitoring externes.
5. Accès admin : Utilisez les clés avec le org_admin rôl’avec parcimonie pour les outils d'administration.
6. Intégrations tierces : Créez des clés restreintes à des apps spécifiques avec le rôle minimum requis.
7. Provisionnement de l'organisation : Utilisez une org_admin ou org_super_admin clé RBAC avec org.create uniquement pour l'automatisation de confiance nécessitant la création d'organisations.

Continuer avec les clés API

Si vous utilisez Clés API pour planifier les flux d'authentification et de compte, le connecter à @capgo/capacitor-social-login pour les détails d'implémentation dans @capgo/capacitor-social-login @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey @capgo/capacitor-native-biometric pour les détails d'implémentation dans @capgo/capacitor-native-biometric, Authentification à deux facteurs pour les détails d'implémentation dans l'authentification à deux facteurs, et SSO (Entreprise) pour les détails d'implémentation dans le SSO (Enterprise).