Aller au contenu principal

Gestion des Clés API

L'interface de gestion des clés API fournit une interface utilisateur basée sur le web pour créer, surveiller et gérer les clés API utilisées pour l'accès programmatique à l'API OmniCRM.

::: note ::: title Remarque :::

Pour des concepts généraux d'authentification API et des exemples d'utilisation, voir concepts_api. :::

Aperçu​

Les clés API permettent une authentification sécurisée et de longue durée pour :

  • Intégrations serveur à serveur
  • Scripts d'automatisation
  • Applications tierces
  • Tâches programmées et jobs cron
  • Systèmes de surveillance externes

Contrairement aux tokens JWT (qui expirent après quelques minutes/heures), les clés API restent valables jusqu'à ce qu'elles soient révoquées manuellement ou jusqu'à leur date d'expiration.

Accéder à la Gestion des Clés API​

Naviguez vers :

Ou directement :

Autorisation requise : MANAGE_API_KEYS (rôle administrateur)

Vue de la Liste des Clés API​

La page principale affiche toutes les clés API sous forme de tableau :

Colonnes :

  • Nom - Étiquette descriptive pour la clé API (par exemple, "Système de Provisionnement", "Outil de Surveillance")
  • Créé par - Nom d'utilisateur de la personne qui a créé la clé
  • Clé API - La chaîne de clé réelle (partiellement masquée pour la sécurité)
  • Statut - Actif, Expiré ou Révoqué
  • Date de création - Date à laquelle la clé a été générée
  • Date d'expiration - Date à laquelle la clé expirera automatiquement
  • Actions - Boutons Modifier, Supprimer, Régénérer

Exemple d'affichage :

Widgets du Tableau de Bord​

En haut de la page, des statistiques récapitulatives sont affichées :

  • Total des Clés API - Nombre total de clés API (actives et inactives)
  • Clés Actives - Clés actuellement valides
  • Expirant Bientôt - Clés expirant dans les 30 jours
  • Clés Expirées - Clés dépassant leur date d'expiration

Création d'une Clé API​

Étape 1 : Cliquez sur "Ajouter une Clé API"

Cliquez sur le bouton + Ajouter en haut à droite de la liste des clés API.

Étape 2 : Remplissez les Détails

Un formulaire modal apparaît demandant :

Nom : ________________________

: (par exemple, "Système de Provisionnement")

Description : __________________

: (Optionnel - but de cette clé)

Date d'expiration : [Sélecteur de Date]

: (Optionnel - laissez vide pour pas d'expiration)

Permissions : ☐ Voir Clients ☐ Créer Clients ☐ Voir Services ☐ Créer Services ☐ Provisionnement ☐ Voir Inventaire ☑ Admin (toutes les permissions)

[Annuler] [Générer la Clé]

Directives pour les Champs :

Nom (obligatoire)

  • Identifiant court et descriptif
  • Exemples : "Système de Provisionnement", "Intégration de Facturation", "Surveillance"
  • Utilisé dans les journaux d'audit et affiché dans la liste

Description (optionnelle)

  • Explication plus détaillée
  • Exemples : "Utilisé par le serveur de provisionnement Ansible", "Synchronisation de facturation tierce"
  • Aide les futurs administrateurs à comprendre l'objectif de la clé

Date d'expiration (optionnelle)

  • Si vide : La clé n'expire jamais (non recommandé)
  • Si définie : La clé devient automatiquement invalide après cette date
  • Recommandé : Définir une expiration pour la sécurité (90 jours à 1 an)

Permissions

  • Sélectionnez des permissions spécifiques ou cochez "Admin" pour un accès complet
  • Suit le même modèle de permissions basé sur les rôles que les comptes utilisateurs
  • Meilleure Pratique : Assigner le minimum de permissions nécessaires

Étape 3 : Générer et Copier la Clé

Après avoir cliqué sur "Générer la Clé", le système affiche la clé API nouvellement créée :

⚠️ Copiez cette clé maintenant - elle ne sera plus affichée !

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

[Copier dans le Presse-papiers]

[Fermer]

::: warning ::: title Avertissement :::

Sauvegardez la clé API immédiatement !

Une fois que vous fermez cette boîte de dialogue, la clé complète ne pourra plus être récupérée. Vous ne verrez qu'une version masquée (sk_live_...XYZ) dans la vue de liste.

Si vous perdez la clé, vous devez la régénérer, ce qui invalide l'ancienne clé et peut casser les intégrations existantes. :::

Étape 4 : Configurez Votre Application

Utilisez la clé API dans les requêtes de votre application :

curl -X GET "https://yourcrm.com/crm/customers" \
  -H "X-API-KEY: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Ou dans des variables d'environnement :

export CRM_API_KEY="sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Gestion des Clés Existantes​

Visualiser les Détails de la Clé​

Cliquez sur le nom de n'importe quelle clé API pour voir tous les détails :

  • Nom complet de la clé et description
  • Horodatage de création
  • Nom d'utilisateur du créateur
  • Permissions associées
  • Statistiques d'utilisation (si mises en œuvre)
  • Journaux d'accès récents

Régénérer une Clé API​

Si une clé API est compromise ou perdue, régénérez-la :

  1. Cliquez sur les ⋮ (trois points) dans la colonne Actions
  2. Sélectionnez "Régénérer la Clé"
  3. Confirmez l'action

::: warning ::: title Avertissement :::

La régénération invalide immédiatement l'ancienne clé.

Toute application utilisant l'ancienne clé cessera de fonctionner. Mettez à jour toutes les intégrations avec la nouvelle clé avant de régénérer. :::

Ce qui se passe :

  • L'ancienne clé est révoquée
  • Une nouvelle clé avec les mêmes permissions est générée
  • La nouvelle clé est affichée (copiez-la immédiatement)
  • Le nom, la description et les permissions restent inchangés

Révoquer (Supprimer) une Clé API​

Pour supprimer définitivement une clé API :

  1. Cliquez sur les ⋮ (trois points) dans la colonne Actions
  2. Sélectionnez "Supprimer"
  3. Confirmez la suppression

Ce qui se passe :

  • La clé est immédiatement révoquée
  • Toutes les requêtes utilisant cette clé retournent 401 Unauthorized
  • La clé est supprimée de la base de données
  • Ne peut pas être annulé - la clé ne peut pas être récupérée

Quand révoquer :

  • L'intégration n'est plus nécessaire
  • La clé a été compromise
  • Le système utilisant la clé a été décommissionné
  • Remplacement par une nouvelle clé avec des permissions différentes

Modifier les Détails de la Clé API​

Pour modifier les détails d'une clé API :

  1. Cliquez sur les ⋮ (trois points) dans la colonne Actions
  2. Sélectionnez "Modifier"
  3. Mettez à jour le nom, la description, l'expiration ou les permissions
  4. Cliquez sur "Sauvegarder les Modifications"

Champs Modifiables :

  • Nom
  • Description
  • Date d'expiration
  • Permissions

Non Modifiable :

  • La valeur de la clé elle-même (utilisez Régénérer pour changer)
  • Date de création
  • Créé par l'utilisateur

Statut de la Clé API​

Les clés API peuvent avoir plusieurs statuts :

Actif

  • La clé est valide et peut être utilisée
  • Dans la date d'expiration (ou pas d'expiration définie)
  • Pas révoquée manuellement
  • Affichée avec un badge vert

Expirant Bientôt

  • Actif mais expirera dans les 30 jours
  • Affichée avec un badge orange/d'avertissement
  • Envisagez de faire tourner avant l'expiration

Expiré

  • Passé la date d'expiration
  • N'accepte plus l'authentification
  • Affichée avec un badge rouge
  • Peut être supprimée ou l'expiration prolongée

Révoqué

  • Supprimé/désactivé manuellement
  • Invalide de manière permanente
  • N'est plus affiché dans la liste active

Filtrage et Recherche​

La liste des clés API prend en charge :

Recherche :

Recherchez par nom, description ou clé partielle :

Filtrer par Statut :

Menu déroulant pour afficher :

  • Toutes les Clés
  • Actives Seulement
  • Expirant Bientôt (dans les 30 jours)
  • Expirées

Trier :

Cliquez sur les en-têtes de colonne pour trier par :

  • Nom
  • Date de création
  • Date d'expiration
  • Créé par

Meilleures Pratiques de Sécurité​

Génération de Clés API​

  • Longueur : Les clés doivent comporter au moins 32 caractères (le système impose cela)
  • Aléatoire : Générées à l'aide de générateurs de nombres aléatoires cryptographiquement sécurisés
  • Format : Typiquement préfixées (par exemple, sk_live_) pour identification

Stockage des Clés API​

Dans le CRM :

  • Les clés sont hachées avant stockage (comme les mots de passe)
  • La clé complète n'est affichée qu'une fois lors de la création
  • La base de données stocke le hachage pour vérification
  • Même les administrateurs ne peuvent pas récupérer la clé complète plus tard

Dans Votre Application :

  • Stockez dans des variables d'environnement, pas dans le code
  • Utilisez des systèmes de gestion de secrets (AWS Secrets Manager, HashiCorp Vault)
  • Ne jamais commettre les clés dans le contrôle de version
  • Faites tourner les clés périodiquement (90-365 jours)

Gestion des Permissions​

  • Principe du Moindre Privilège - Accordez uniquement les permissions nécessaires
  • Évitez de créer des clés administratives sauf si absolument nécessaire
  • Utilisez des clés séparées pour différents systèmes/buts
  • Révisez régulièrement les permissions

Surveillance et Audit​

  • Surveillez l'utilisation des clés API via des journaux d'activité
  • Configurez des alertes pour des modèles d'accès inhabituels
  • Révisez régulièrement les horodatages "dernier utilisé"
  • Supprimez les clés inutilisées

Rotation des Clés​

Établissez une politique de rotation des clés :

  1. Créez une nouvelle clé avec les mêmes permissions
  2. Mettez à jour les applications pour utiliser la nouvelle clé
  3. Surveillez pour vous assurer que l'ancienne clé n'est plus utilisée
  4. Révoquez l'ancienne clé après la période de grâce

Dépannage​

"401 Unauthorized" lors de l'utilisation de la clé API

  • Cause : Clé invalide, expirée ou incorrecte
  • Solution :
    • Vérifiez que la clé est copiée correctement (pas d'espaces supplémentaires)
    • Vérifiez le statut de la clé (Actif vs. Expiré)
    • Confirmez que la clé a les permissions requises
    • Assurez-vous d'utiliser l'en-tête X-API-KEY (pas Authorization)

"Clé API non trouvée" après création

  • Cause : La clé a peut-être été créée mais pas correctement stockée
  • Solution :
    • Vérifiez la liste des clés API pour la nouvelle entrée
    • Si manquante, créez une nouvelle clé
    • Signalez le problème à l'administrateur

Clé API expirant bientôt

  • Cause : Date d'expiration approchant (dans les 30 jours)
  • Solution :
    • Créez une nouvelle clé avec une expiration prolongée
    • Mettez à jour les applications pour utiliser la nouvelle clé
    • Révoquez l'ancienne clé après la migration

Impossible de supprimer la clé API

  • Cause : Peut être protégée ou en cours d'utilisation
  • Solution :
    • Assurez-vous d'avoir les permissions administratives
    • Vérifiez si la clé est verrouillée/protégée
    • Contactez l'administrateur si le problème persiste

Points de Terminaison API (pour la Gestion Programmatique)​

Les clés API peuvent également être gérées via l'API (nécessite des permissions administratives) :

Lister les Clés API

GET /crm/api-keys
Authorization: Bearer <admin-token>

Créer une Clé API

POST /crm/api-keys
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Nouvelle Intégration",
  "description": "Synchronisation de facturation tierce",
  "expiry_date": "2026-01-10",
  "permissions": ["view_customer", "view_service"]
}

Réponse :

{
  "api_key_id": 123,
  "name": "Nouvelle Intégration",
  "api_key": "sk_live_a1b2c3d4e5f6g7h8i9j0",
  "status": "active",
  "created": "2025-01-10T10:00:00Z",
  "expiry_date": "2026-01-10T23:59:59Z"
}

Révoquer la Clé API

DELETE /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>

Mettre à Jour la Clé API

PATCH /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Nom Mis à Jour",
  "expiry_date": "2026-12-31"
}

Cas d'Utilisation Courants​

Cas d'Utilisation 1 : Intégration du Système de Provisionnement

Créez une clé API pour votre serveur de provisionnement Ansible :

  1. Naviguez vers Clés API → Ajouter
  2. Nom : "Serveur de Provisionnement Ansible"
  3. Description : "Utilisé par l'automatisation de provisionnement"
  4. Permissions : Provisionnement, Voir/Créer Services, Voir/Mettre à Jour Inventaire
  5. Expiration : 1 an
  6. Copiez la clé et ajoutez-la au crm_config.yaml d'Ansible

Cas d'Utilisation 2 : Intégration de Facturation Tierce

Créez une clé en lecture seule pour l'exportation de facturation :

  1. Nom : "Synchronisation de Facturation - QuickBooks"
  2. Permissions : Voir Clients, Voir Transactions, Voir Factures
  3. Expiration : 90 jours (rotation trimestrielle)
  4. Utilisez dans le script d'exportation programmé

Cas d'Utilisation 3 : Surveillance et Alerte

Créez une clé pour la collecte de métriques Prometheus/Grafana :

  1. Nom : "Surveillance - Grafana"
  2. Permissions : Voir Services, Voir Provisionnement
  3. Expiration : Jamais (la surveillance nécessite un accès continu)
  4. Configurez dans la source de données Grafana

Cas d'Utilisation 4 : API du Portail Client

Créez une clé pour le portail d'auto-service client :

  1. Nom : "Backend du Portail Client"
  2. Permissions : Voir Son Propre Client, Voir Ses Propres Services, Créer des Paiements
  3. Expiration : 180 jours
  4. Utilisez dans les appels API du backend du portail

Documentation Connexe​

  • concepts_api - Concepts et exemples d'authentification API
  • rbac - Contrôle d'accès basé sur les rôles et permissions
  • 2fa - Authentification à deux facteurs pour une sécurité supplémentaire