Skip to content
Documentation Wasel

13 — API Externes et Clés

1. Objectif métier

Section titled “1. Objectif métier”

Contrôler l’accès des systèmes externes à WASEL avec des clés dédiées, afin de:

  • sécuriser les intégrations,
  • limiter les usages non autorisés,
  • tracer clairement qui consomme quoi.

2. Qui utilise ce module (admin/operator)

Section titled “2. Qui utilise ce module (admin/operator)”
  • admin: crée, active, limite, fait tourner et révoque les clés externes.
  • operator: informé des intégrations actives, sans gérer les secrets.

3. Prérequis

Section titled “3. Prérequis”

Avant de créer une clé:

  • inventaire des intégrations externes (outil, environnement, propriétaire),
  • besoin fonctionnel validé (messagerie, OTP, ou les deux),
  • politique interne de rotation et révocation validée,
  • stratégie IP autorisées définie si nécessaire.

Contraintes importantes:

  • la clé complète n’est visible qu’une seule fois lors de la création,
  • une clé inactive ne peut plus être utilisée,
  • le périmètre d’usage doit être défini au minimum nécessaire,
  • le nom de clé doit être distinct pour éviter les confusions.

4. Procédure pas-à-pas (orientée actions produit)

Section titled “4. Procédure pas-à-pas (orientée actions produit)”
  1. Créer une clé par intégration et par environnement.
  • Exemple: ERP-prod, ERP-preprod, Auth-OTP-prod.
  1. Choisir le périmètre minimal.
  • Messagerie externe,
  • OTP uniquement,
  • ou périmètre élargi selon besoin validé.
  1. Définir les garde-fous.
  • Limite de débit cible,
  • liste d’IP autorisées si applicable,
  • activation immédiate ou différée.
  1. Partager la clé via un canal sécurisé.
  • Transmission nominative,
  • jamais dans un canal public,
  • confirmation de réception côté partenaire.
  1. Tester l’intégration en environnement contrôlé.
  • Vérifier que la clé fonctionne uniquement dans le périmètre attendu.
  1. Surveiller les usages.
  • Vérifier date de dernière utilisation,
  • détecter les clés dormantes,
  • désactiver les clés obsolètes.
  1. Organiser la rotation régulière.
  • Créer une nouvelle clé,
  • basculer l’intégration,
  • désactiver l’ancienne clé.
  1. Réagir aux incidents.
  • En cas de doute: désactivation immédiate,
  • création d’une nouvelle clé,
  • audit d’usage post-incident.

5. Scénarios concrets (minimum 2)

Section titled “5. Scénarios concrets (minimum 2)”

  • Scénario A (partenaire notifications):

    • clé dédiée à l’envoi de notifications transactionnelles,
    • périmètre limité à la messagerie,
    • IP partenaire autorisée.

  • Scénario B (service d’authentification):

    • clé dédiée OTP,
    • isolation complète du reste des usages,
    • rotation trimestrielle.

  • Scénario C (incident sécurité):

    • suspicion de fuite,
    • clé désactivée immédiatement,
    • nouvelle clé émise et redéployée.

6. Erreurs fréquentes et résolution

Section titled “6. Erreurs fréquentes et résolution”

  • Problème: accès refusé malgré clé existante.

  • Causes fréquentes: clé inactive, périmètre insuffisant, IP non autorisée.

  • Résolution: vérifier d’abord l’état de la clé, puis le périmètre et la politique IP.

  • Problème: clé perdue.

  • Cause: la clé complète n’est plus récupérable après création.

  • Résolution: créer une nouvelle clé et remplacer l’ancienne.

  • Problème: usages mélangés entre équipes.

  • Cause fréquente: une clé partagée entre plusieurs systèmes.

  • Résolution: appliquer une clé par système/environnement.

7. Bonnes pratiques et limites

Section titled “7. Bonnes pratiques et limites”
  • Une clé = une intégration = un propriétaire.
  • Séparer les clés par environnement (test vs production).
  • Réduire le périmètre au strict nécessaire.
  • Activer la restriction IP quand c’est possible.
  • Planifier une rotation régulière et documentée.

Limites:

  • une clé trop permissive augmente le risque opérationnel,
  • une clé partagée complique fortement les audits,
  • sans gouvernance de rotation, le risque sécurité s’accumule.

8. Référence rapide (champs/statuts/modes)

Section titled “8. Référence rapide (champs/statuts/modes)”

Champs de gouvernance:

  • name,
  • scope,
  • rate_limit,
  • allowed_ips,
  • is_active,
  • key_prefix,
  • last_used_at.

Périmètres courants:

  • template_messaging,
  • otp.

Cycle de vie:

  • création,
  • activation,
  • supervision,
  • rotation,
  • révocation.

9. Liens vers modules liés

Section titled “9. Liens vers modules liés”