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 clair n'est visible qu'une seule fois.

En utilisant 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é :

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

Certains endpoints acceptent également une en-tête de clé dédiée. Les Les canaux API accepte authorization ou capgkeyutilisez l'une de ces en-têtes pour l'automatisation de la préversion.

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 à travers l'application web ou API, vous affectez des rôles à deux niveaux :

• Rôle d'organisation — Définit les permissions de base de la clé sur l'ensemble de l'organisation (par exemple, org_admin ou org_member).
• App roles — Permissions par application (par exemple, app_admin, app_developer, app_uploader, app_reader, 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

Lier app_preview Seulement pour l'application de prévisualisation pour 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.appLa liaison reste liée à l'organisation même si la clé n'a pas de rôl’organisationnel.

Le niveau de l'application app_preview le rôle ne comprend que app.read, app.read_bundles, app.upload_bundle, et app.create_channel. Lorsque cette clé crée un canal, Capgo ajoute automatiquement un channel_preview liaison sur le nouveau canal créé. Cette liaison enfant accorde channel.read, channel.promote_bundle, et channel.delete seulement pour le canal que la clé a créé.

app_preview retient app.read, 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. Les liaisons enfants automatiques limitent mutations de cycle de vie à le canal que la clé a créé.

Capgo enregistre la clé de prévisualisation d'application qui a téléchargé chaque bundle. La clé peut promouvoir uniquement son propre bundle 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 bundle d'une autre clé. Pour ce flux de travail, omisez public et n'utilisez jamais --default.

Utilisez channel delete <preview-channel> <public-app-id> --delete-bundle Cette route de nettoyage est atomique et vérifie la propriété. Elle supprime uniquement le canal de prévisualisation et le bundle lié au clé appelante. 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 Use an App Preview key for preview workflows.

Remarque

Clés sans liaisons de rôle retournent à un système basé sur la mode legacy (read, upload, write, allCes modes sont dépréciés — utilisez les rôles RBAC à la place.

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 normaux d'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 en global_permissions.
• La même clé API doit également avoir une organisation-scopée org_admin ou org_super_admin binding.
• Nouveaux API clés ne reçoivent pas org.create Les nouvelles clés __CAPGO_KEEP_0__ n'ont pas reçu Permettre la création d'organisations lors de la création ou de la modification d'une clé RBAC API dans le tableau de bord.
• Existing write-capable org admin/super admin API keys were backfilled with org.create Ainsi, les intégrations existantes peuvent 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'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 seulement s'applique à 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.

Sous-titre « 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 texte brut une seule fois. Seule une hachage est stocké. Cela signifie :

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

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

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 :

• Expiration obligatoire (require_apikey_expiration) — All new keys must have an expiry.
• Maximum TTL (max_apikey_expiration_days) — L'expiration ne peut pas être plus éloignée de N jours de maintenant.

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ère vos API clés périodiquement à l'aide de la fonctionnalité de régénération
3. Stockage SécuriséStockez les clés API de manière sécurisée et n'y commettez jamais les modifications de version.
4. Utilisation de Clés Chiffrées: Créez des clés sécurisées (chiffrées) pour les intégrations de production
5. Expiration de la clé: Définissez toujours une date d'expiration sur les clés utilisées pour l'accès temporaire ou CI/CD
6. Restrictions de portée: Limitez les clés aux applications spécifiques avec le rôle requis minimum

Utilisations courantes

1. Intégration CI/CD: Créez des clés scoping spécifiques aux applications avec le app_uploader ou app_developer rôle, et définir une date d'expiration.
2. rôle, et définissez une date d'expiration.: Use app_preview seulement dans l'application de prévisualisation ou les applications 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. : Créez des clés avec leAccès Administratif app_reader réservé pour les outils administratifs.
5. Intégrations de Tiers: Utilisez les clés avec le org_admin role sparingly for administrative tools.
6. role for automated deployment scripts.Créez des clés restreintes à des applications spécifiques avec le rôle requis minimum.
7. Provisionnement d'organisation: Utilisez un org_admin ou org_super_admin Clé RBAC avec org.create seulement pour l'automatisation fiable qui doit créer des organisations.

Continuez de API Clés

Si vous utilisez les __CAPGO_KEEP_0__ Clés Clés API @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-connexion-social @capgo/capacitor-connexion-social pour les détails d'implémentation dans @capgo/capacitor-connexion sociale, @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey @capgo/capacitor-native-biometrique 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 SSO (Entreprise).