API clés

API clés 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 finement granulaire. Chaque clé peut également avoir une date d'expiration facultative et peut être créée sous forme de « clé sécurisée » (hachée) où la valeur au texte brut n'est visible qu'une seule fois.

Utilisation d'une clé API

Utilisez l'en-tête d'authentification documentée par l'endpoint. Pour les requêtes avec 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 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

API clés utilisent le même système de contrôle d'accès basé sur les rôles (RBAC) que les comptes d'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é à l'échelle 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_reader, ou app_preview).

Si une clé API a des liaisons de rôle explicites, seules ces liaisons sont évaluées 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 seul au canal de prévisualisation de l'application de 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 enregistrement de l'application, et non l'identifiant public de l'application utilisé par les commandes CLI (par exemple, com.example.app). La liaison reste liée à l'organisation même si la clé n'a pas de rôle organisationnel.

Niveau de l'application app_preview rôle comprend uniquement app.read, app.read_bundles, app.upload_bundle, et app.create_channel. Lorsque la 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, 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 mutations de cycle de vie à seulement 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 workflow, omisez public et n'utilisez jamais --default.

Utilisez channel delete <preview-channel> <public-app-id> --delete-bundle pour la mise à jour. C'est une route de mise à jour atomique, vérifiée en matière de propriété, d'une prévisualisation de mise à jour ; elle supprime uniquement le canal de prévisualisation et le paquet 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.

Remarque

Les clés sans liaisons de rôle retournent à un système basé sur des modes (read, upload, write, all). Ces modes sont dépréciés — utilisez les rôles RBAC à la place.

La 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 séparée des liens de rôle normal org/app car une nouvelle organisation n'existe pas encore lorsqu'elle est appelée. Pour créer des organisations avec une clé __CAPGO_KEEP_0__ : POST /organization/ La clé API doit inclure

• The API key must include org.create Même la clé __CAPGO_KEEP_0__ doit également avoir un lien d'organisation actuel-scoped global_permissions.
• The same API key must also have a current organization-scoped org_admin Le lien de clé __CAPGO_KEEP_0__ ne reçoit pas org_super_admin par défaut. Activez
• New API keys do not receive org.create lors de la création ou de la modification d'une clé RBAC __CAPGO_KEEP_0__ dans le tableau de bord. La clé __CAPGO_KEEP_0__ doit être définie avant de créer une organisation. La clé API doit être définie avant de créer une organisation.
• Les administrateurs/super administrateurs existants de l'organisation pouvant écrire les clés API ont été réinsérés 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 le API, incluez global_permissions en même temps la liaison de rôle de l'administrateur 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 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)

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

• La clé en clair 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 « politique de l'org ». enforce_hashed_api_keys Expiration

La section intitulée « Expiration »

Les politiques d'organisation peuvent imposer :

Expiration obligatoire

• ) — Toutes les nouvelles clés doivent avoir une date d'expiration. (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é

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ûr : Stockez vos API clés de manière sécurisée et n'y commettez jamais
4. Utilisation de Clés Hachées : Créez des clés sécurisées (hachées) pour les intégrations de production
5. Fixer l'expiration: Définissez toujours une date d'expiration sur les clés utilisées pour l'accès temporaire ou l'accès CI/CD
6. Restrictions d'Espace: 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éfinissez une date d'expiration.
2. Canaux de prévisualisation des PR: Utilisez app_preview On ne publie que sur 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 mise en production: Utilisez les clés avec le app_developer rôle pour les scripts de mise en production 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 administrateur: Utilisez les clés avec le org_admin rôle avec parcimonie pour les outils administratifs.
6. Intégrations tierces: 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 API Clés pour planifier l'authentification et les flux de compte, connectez-le avec @capgo/capacitor-connexion-social pour les détails d'implémentation dans @capgo/capacitor-connexion-social, @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 Authentification à deux facteurs, et SSO (Entreprise) pour les détails d'implémentation dans SSO (Entreprise).