Authentification

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

Couche	Rôle	Mécanisme
mTLS	preuve d’identité machine	Cert client X.509 signé par votre CA, vérifié au TLS handshake côté SmartWatt
Bearer scopé	preuve d’autorisation applicative	Token généré en self-service depuis votre espace dashboard SmartWatt

mTLS (obligatoire)

Principe

Pour chaque appel HTTPS sur /api/v*/energy-programs/*, votre client présente un cert client signé par votre CA root. SmartWatt valide le cert contre votre CA root enregistrée chez nous, puis vérifie côté SmartWatt la cohérence avec votre identité applicative.

Onboarding cert client

1. Vous générez votre CA root (ou réutilisez celle de votre PKI corporate) et émettez un cert client à partir d’elle.
2. Vous nous transmettez la CA root
3. Vous nous communiquez le sha256 du PEM
4. Vous nous indiquez le subject DN attendu du cert client (ex. CN=bsp.example.fr,O=Example,C=FR). On l’enregistre côté SmartWatt.
5. SmartWatt déploie votre CA, on vous notifie l’activation.

À partir de là, tout appel sans cert ou avec un cert signé par une autre CA est refusé au TLS handshake (alert bad certificate) ou côté SmartWatt (403 MTLS_REQUIRED / 403 MTLS_SUBJECT_MISMATCH).

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).

Rotation CA

Si vous faites tourner votre CA root :

1. Vous nous transmettez la nouvelle CA
2. SmartWatt concatène nouvelle + ancienne pendant la transition. Vos certs anciens et nouveaux sont acceptés simultanément
3. Une fois votre flotte cliente migrée, nous retirons l’ancienne CA
4. Délai recommandé : 7 jours minimum, 30 jours typique

Si votre cert client fuite

Révoquez le cert dans votre PKI et émettez-en un nouveau signé par la même CA root, pas d’action côté SmartWatt nécessaire (la CA root reste valide).

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é :

Scope	Endpoint
inbound:programme-soutirage	POST /api/v*/energy-programs/programme-soutirage
outbound:besoins-agreges	GET /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 (CA + Subject DN enregistrés côté SmartWatt) 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.