API Keys

API est utilisé 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.

Utiliser une clé API

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

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

Certains endpoints acceptent également une clé de tête dédiée. Les acceptent les canaux API ou authorization ; utilisez l'une de ces en-têtes pour l'automatisation du canal de prévisualisation. capgkeyPermissions RBAC

Section intitulée « Permissions RBAC »

Les API clés utilisent le même système de contrôle d'accès basé sur le rôle (RBAC) que les comptes d'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é à 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 de permission. Les permissions personnelles du propriétaire de la clé ne sont pas héritées par la clé.

Automatisation du canal de prévisualisation

Se lier uniquement à l'application de prévisualisation pour la CI qui crée un canal de prévisualisation temporaire et non public, charge et promeut un bundle, puis supprime les deux. app_preview Copier dans le presse-papier

{
  "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 s'agit de l'UUID interne du registre de l'application, et non de l'identifiant d'application public utilisé par les commandes __CAPGO_KEEP_0__ (par exemple, app_id is the app record’s internal UUID, not the public app identifier used by CLI commands (for example, com.example.appLe rôle d'application

comprend uniquement app_preview , et app.read, app.read_bundles, app.upload_bundle. Lorsque la 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_bundleLorsque la clé crée un canal, __CAPGO_KEEP_0__ ajoute automatiquement un lien de rôle sur le nouveau canal créé. Ce lien enfant accorde les rôles d'application et de canal. channel.delete seulement pour le canal créé par la clé.

app_preview retient app.read, ce n'est donc pas une isolation stricte de lecture de canal : la clé peut lister les métadonnées du canal sélectionné dans l'application. les mutations de cycle de vie sont limitées au canal créé par la clé.

Capgo enregistre la clé de prévisualisation de l'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 pas d'accès aux mutations de cycle de vie d'un canal existant par défaut/main, d'un canal créé par une autre clé de prévisualisation ou du bundle d'une autre clé. Pour ce workflow, omittre public et n'utilisez jamais --default.

Utilisez channel delete <preview-channel> <public-app-id> --delete-bundle pour la suppression. C'est une route de suppression atomique, vérifiée en termes d'appartenance, de prévisualisation ; elle supprime uniquement le canal de prévisualisation et le bundle lié appelant. app_preview ne concède pas une autorisation générique bundle.delete.

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

Note

Les clés sans liaisons de rôle retombent sur un système basé sur la mode (read, upload, write, all). Ces modes sont déconseillés — utilisez les rôles RBAC au lieu de cela.

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 liaisons de rôle normales d'application/organisation 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 en global_permissions.
• The same API key must also have a current organisation-encadrée org_admin ou org_super_admin liaison.
• Nouvelles API clés ne reçoivent org.create par défaut. Activer Permettre la création d'organisations lors de la création ou de la modification d'une clé RBAC API dans l'interface de dashboard.
• Existing write-capable org admin/super admin API keys were backfilled with 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 comme 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 côté l'administrateur de l'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 de 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 le matériau de clé et renvoie la valeur en clair une fois. Seul un hachage est stocké. Cela signifie :

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

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

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) — Toutes les nouvelles clés doivent avoir une date d'expiration.
• Durée de vie maximale (max_apikey_expiration_days) — La date d'expiration ne peut pas être supérieure de N jours à celle d'aujourd'hui.

Meilleures Pratiques de Sécurité

1. Principe de la Moindre Autorité: Attribuez le rôle le plus restrictif qui permet toujours à votre intégration de fonctionner
2. Rotation régulière: Roulez périodiquement vos API clés en utilisant 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 la version de contrôle
4. Utilisation de clés hachées: Créez des clés sécurisées (hachées) pour les intégrations de production
5. Expiration: Fixez 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éfinissez une date d'expiration.
2. Canaux de prévisualisation des PR: Utilisez app_preview sur uniquement l'application de prévisualisation ou les applications lorsque CI doit télécharger un bundle, créez un canal temporaire, et nettoyez atomiquement votre propre canal et bundle.
3. Automatisation de déploiement: Utilisez des 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 surveillance externe.
5. Accès Administrateur: Utilisez des 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 de l'Organisation: Utilisez une org_admin ou org_super_admin clé RBAC avec org.create seulement pour l'automatisation fiable qui nécessite la création d'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-biométrie-native pour les détails d'implémentation dans @capgo/capacitor-biométrie-native, La deuxième facteur d'authentification pour les détails d'implémentation dans la deux facteurs d'authentification, et SSO (Entreprise) pour les détails d'implémentation dans SSO (Entreprise).