Authentification

Schéma d'authentification entre SmartWatt et l'opérateur de marché.

L’authentification des appels API combine deux couches obligatoires, vérifiées indépendamment côté SmartWatt :

CoucheRôleMécanisme
mTLSpreuve d’identité machineCert client X.509 émis par la CA SmartWatt, vérifié au handshake
Bearer scopépreuve d’autorisation applicativeToken généré en self-service depuis votre espace dashboard SmartWatt

mTLS (obligatoire)

Principe

SmartWatt est l’autorité de certification. Vous générez votre paire de clés et nous transmettez une demande de signature (CSR) ; nous vous renvoyons votre certificat client signé par notre CA.

Votre clé privée ne quitte jamais votre infrastructure — vous ne nous l’envoyez pas, et nous n’en avons jamais besoin.

Pour chaque appel HTTPS sur /api/v*/energy-programs/*, votre client présente ce certificat. SmartWatt le valide contre sa propre CA racine au TLS handshake, puis vérifie la cohérence avec votre identité applicative.

Onboarding cert client

  1. Vous générez votre paire de clés et un CSR, et conservez la clé privée chez vous :

    openssl req -new -newkey rsa:4096 -nodes \
  -keyout mon-operateur.key \
  -out mon-operateur.csr \
  -subj "/CN=bsp.example.fr/O=Example/C=FR"

    Le CN/O/C que vous choisissez ici deviennent le subject enregistré côté SmartWatt : indiquez votre identité réelle d’opérateur.

  2. Vous nous transmettez le CSR (le bloc -----BEGIN CERTIFICATE REQUEST----- … -----END CERTIFICATE REQUEST-----), de préférence en pièce jointe : un copier-coller dans le corps d’un mail casse souvent les sauts de ligne.

  3. Vous nous communiquez le SHA256 de votre clé publique par un canal différent (téléphone, messagerie sécurisée — pas le même mail que le CSR) :

    openssl req -in mon-operateur.csr -pubkey -noout | sha256sum

    Ce hash porte sur la clé publique, pas sur le fichier : il ne change pas si le CSR est reformaté au transport. Transmis par un second canal, il nous prouve que le CSR reçu est bien le vôtre.

  4. SmartWatt signe votre CSR et vous renvoie votre certificat client. Nous enregistrons au passage le subject du certificat.

  5. Vous déployez ce certificat avec votre clé privée sur votre client ; nous vous notifions l’activation.

À partir de là, tout appel sans certificat, ou avec un certificat que nous n’avons pas émis, est refusé au TLS handshake (alert bad certificate) ou côté SmartWatt (403 MTLS_REQUIRED / 403 MTLS_SUBJECT_MISMATCH).

Ne nous envoyez jamais votre clé privée (un bloc -----BEGIN PRIVATE KEY-----). Si cela arrive par erreur, considérez-la comme compromise : détruisez-la de votre côté et refaites un CSR avec une nouvelle paire de clés.

Propagation

Le subject du cert validé est propagé côté SmartWatt via le header standard X-Forwarded-Client-Cert :

X-Forwarded-Client-Cert: Hash=<sha256-du-cert>;Subject="CN=bsp.example.fr,O=Example,C=FR"

Vous n’avez rien à faire côté client : votre client TLS standard suffit. Le header X-Forwarded-Client-Cert est posé par nous, vous ne devez pas l’injecter vous-même (le serveur efface tout X-Forwarded-Client-Cert entrant avant routage).

Renouvellement de votre certificat

Votre certificat a une date d’expiration. Pour le renouveler :

  1. Vous générez une nouvelle paire de clés et un nouveau CSR (même procédure qu’à l’onboarding).
  2. Vous nous transmettez le CSR, avec le SHA256 de la nouvelle clé publique par canal séparé.
  3. SmartWatt signe et vous renvoie le nouveau certificat.
  4. Vous basculez votre client dessus.

Anticipez : prévenez-nous au moins 7 jours avant l’expiration pour couvrir l’aller-retour de signature.

Si votre clé privée ou votre certificat fuite

  1. Prévenez immédiatement SmartWatt. C’est nous qui révoquons : votre accès est suspendu côté SmartWatt, ce qui bloque le certificat compromis pour tous les appels.
  2. Vous générez une nouvelle paire de clés et un nouveau CSR, et nous le transmettez (avec le hash par canal séparé).
  3. Nous signons, vous renvoyons un nouveau certificat, puis réactivons votre accès.

Vous n’avez aucune révocation à faire dans une PKI de votre côté : le certificat ayant été émis par SmartWatt, la révocation nous incombe.

Bearer scopé (obligatoire)

Format

En plus du cert client, chaque appel embarque un token Bearer :

Authorization: Bearer swt_<base64url 32 octets>

Format : préfixe swt_ + 256 bits d’entropie. Le préfixe permet la détection automatique de fuite (GitHub secret scanning, gitleaks, etc.).

Génération

Vous générez votre token en self-service depuis votre espace dashboard SmartWatt, page Profil → Tokens API (dashboard.smartwatt.fr/profile/api-tokens). Le token est affiché une seule fois à la création : stockez-le immédiatement dans votre gestionnaire de secrets.

Si vous le perdez, vous ne pouvez pas le récupérer (le serveur ne conserve que son hash) ; il faut en générer un nouveau et révoquer l’ancien.

Scopes

Le token hérite des scopes attachés à votre compte. Pour les opérateurs de marché :

ScopeEndpoint
inbound:programme-soutiragePOST /api/v*/energy-programs/programme-soutirage
outbound:besoins-agregesGET /api/v*/energy-programs/besoins-agreges

Un appel avec un token sans le scope requis reçoit 403 SCOPE_DENIED.

Rotation et révocation

Vous pouvez générer un nouveau token et révoquer l’ancien à tout moment depuis votre espace dashboard. Recommandation : 2 tokens valides simultanément pendant la transition (≥ 7 jours), puis révocation de l’ancien.

Si votre token fuite

  1. Révoquez immédiatement le token compromis depuis votre espace dashboard
  2. Générez-en un nouveau et déployez-le
  3. La révocation est effective sous quelques secondes

Modèle organisationnel

SmartWatt vous identifie comme entreprise, pas comme personne physique. Concrètement :

  • Votre entreprise a un cert client mTLS — émis par la CA SmartWatt, son subject enregistré chez nous — qui authentifie toutes vos requêtes machine.
  • Plusieurs tokens Bearer simultanés sont possibles côté votre entreprise. Chaque membre habilité génère le sien depuis son espace dashboard, tous restent valides en parallèle. Tous sont liés à votre entreprise, donc tous compatibles avec le même cert client.
  • Les scopes (inbound:programme-soutirage, outbound:besoins-agreges) sont attachés au token individuel : un token peut n’avoir qu’un sous-ensemble de scopes.

Cohérence mTLS ↔ Bearer

Vos tokens Bearer et votre cert client sont rattachés à la même entreprise. Un token volé (= compromission gestionnaire de secrets, log) ne peut pas être réutilisé sans présenter votre cert client mTLS au TLS handshake. Un attaquant externe à votre infra ne pourra pas appeler l’API même avec votre token en main.

Traçabilité interne

Le mécanisme n’identifie pas l’utilisateur derrière l’appel : SmartWatt trace votre entreprise et l’ID du token utilisé. Pour distinguer qui a appelé en interne chez vous, convention recommandée : 1 token par utilisateur, jamais partagé, et nommer le token avec le prénom/email du porteur dans la console. L’audit log SmartWatt expose le nom du token utilisé pour chaque appel.