Les API HTTP authentifient les appelants avec un identifiant dans l'en-tête Authorization — une clé d'API ou un bearer token (Authorization: Bearer <token>). Les schémas plus forts signent chaque requête avec un HMAC sur une requête canonique pour que les identifiants ne soient jamais rejouables, utilisent OAuth 2.0 client-credentials pour les tokens machine à machine, et ajoutent le TLS mutuel là où une identité au niveau transport est requise.
Bearer tokens et clés d'API
L'authentification la plus simple est un identifiant bearer : le client présente un token secret dans l'en-tête Authorization et le serveur le valide. RFC 9110 définit l'en-tête Authorization et son préfixe de schéma, et OAuth 2.0 définit le schéma Bearer — Authorization: Bearer <token> — dont la propriété déterminante est que la simple possession donne accès, si bien que le token ne doit voyager que sur TLS et ne jamais apparaître dans une URL, un journal ou un message d'erreur. Une clé d'API est la même idée avec un secret à durée de vie plus longue, souvent sans expiration. Comme un identifiant bearer est rejouable s'il est capturé, il est la base et non le plafond : facile à intégrer et parfaitement adéquat sur TLS pour la plupart du trafic, mais les opérations à forte valeur superposent souvent une signature de requête par-dessus.
POST /v1/messages HTTP/1.1
Host: api.example
Authorization: Bearer eyJhbGciOi... # secret; TLS only, never logged
Content-Type: application/jsonSignature de requête HMAC
La signature de requête relève le niveau : au lieu d'envoyer le secret, le client s'en sert pour calculer un HMAC sur une représentation canonique de la requête, et n'envoie que la signature. Le serveur, détenant le même secret, recalcule la signature et compare. Comme la signature couvre la méthode, le chemin, les en-têtes clés et un hash du corps, une signature capturée ne peut être rejouée contre une requête différente, et comme le secret lui-même ne quitte jamais le client, capturer une requête ne révèle pas l'identifiant. La construction reflète la signature de webhook dans l'autre sens et repose sur la même primitive HMAC-SHA256 (RFC 2104 / RFC 6234). La partie délicate est la requête canonique : les deux parties doivent s'accorder octet pour octet sur la façon de la sérialiser, sinon toute signature diverge.
canonical =
HTTP-METHOD + '\n' +
URI-PATH + '\n' +
SORTED-QUERY + '\n' +
SIGNED-HEADERS (name:value, sorted, '\n'-joined) + '\n' +
HEX(SHA256(raw_body))
signature = HMAC_SHA256(secret, canonical)
Authorization: SIGV1 Credential=<key-id>,
SignedHeaders=host;x-date;content-type, Signature=<hex>En-têtes signés et date de requête
Deux détails rendent la signature de requête solide. Premièrement, une liste SignedHeaders explicite nomme exactement quels en-têtes sont couverts, de sorte qu'un intermédiaire qui ajoute ou réordonne des en-têtes sans rapport n'invalide pas la signature, tandis que tout en-tête que le client a choisi de signer est infalsifiable de façon détectable. Deuxièmement, une date de requête (un X-Date signé ou l'en-tête Date standard) fait partie de la requête canonique et est vérifiée contre l'horloge du serveur dans une tolérance — la même défense contre le rejeu que les webhooks, appliquée aux appels d'API entrants. Ensemble, ils font qu'une requête signée est liée à son contenu exact, à ses en-têtes déclarés et à une fenêtre de temps étroite ; une requête capturée est inutile quelques minutes plus tard.
Cadrage et rotation des clés
Les identifiants devraient porter le moindre privilège qui fonctionne et être rotatables sans interruption. Le cadrage attache des permissions à une clé — quelles opérations elle peut appeler, depuis quelle source, à quel débit — de sorte qu'une clé qui ne fait qu'envoyer des messages ne puisse lire les paramètres du compte, et le rayon d'impact d'une clé compromise soit borné. La rotation suit le motif de chevauchement des clés : émettre un nouvel identifiant, exécuter les deux en parallèle pendant la migration des clients, puis révoquer l'ancien, pour que rien ne casse en cours de route. Les clés devraient être identifiables (un id de clé non secret voyage dans la requête pour que le serveur sache contre quel secret vérifier et quel cadre appliquer) et révocables individuellement, pour qu'une intégration compromise soit coupée sans perturber les autres.
| Schéma | Ce qui transite | Force / utilisation |
|---|---|---|
| Clé API | Secret de longue durée dans Authorization | Base simple ; TLS obligatoire ; risque de fuite dans les journaux |
| Jeton porteur (OAuth 2.0) | Jeton d'accès temporaire | Expirant, à portée limitée ; renouvelé via le point de terminaison de jeton |
| Signature HMAC des requêtes | Signature (le secret reste local) | Résistant au rejeu, falsification détectable pour chaque requête |
| mTLS | Certificat client X.509 | Identité au niveau transport ; robuste mais exploitation plus lourde |
TLS mutuel
Le TLS mutuel authentifie le client à la couche transport : en plus du serveur présentant un certificat, le client présente son propre certificat X.509 durant la poignée de main, et le serveur n'admet que les connexions dont le certificat remonte à une AC de confiance et correspond à une identité enrôlée. Cela lie l'identité d'API à une clé cryptographique gérée au niveau de la connexion plutôt qu'à un secret bearer dans un en-tête, ce qui est attrayant pour les liens machine à machine à haute assurance et pour épingler un partenaire à des certificats spécifiques. Le coût est opérationnel — émission, distribution, rotation et révocation des certificats — si bien que le mTLS est typiquement réservé aux intégrations les plus sensibles, souvent combiné à un bearer token ou une signature pour une autorisation fine par-dessus l'identité de transport grossière.
OAuth 2.0 client-credentials pour le M2M
Pour les intégrations de serveur à serveur sans utilisateur final présent, OAuth 2.0 (RFC 6749) définit le flux client-credentials. Le client s'authentifie auprès d'un endpoint de token avec son client_id et son client_secret (ou un certificat client) et reçoit un access token à courte durée de vie, qu'il présente ensuite comme bearer token sur les appels d'API jusqu'à son expiration et son renouvellement. L'avantage sur une clé d'API statique est la durée de vie et le cadre : les tokens sont à courte durée de vie, si bien qu'un token capturé expire vite, et ils portent des cadres explicites, si bien qu'un token forgé pour l'envoi ne peut servir à administrer le compte. C'est le motif standard pour l'accès d'API machine à machine et le mécanisme que le guide d'authentification de BroadNet documente concrètement pour ses endpoints.
POST /oauth/token HTTP/1.1
Host: auth.example
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=<id>
&client_secret=<secret>
&scope=messages:send
-> { "access_token": "...", "token_type": "Bearer",
"expires_in": 3600, "scope": "messages:send" }Questions fréquemment posées
Quelle est la différence entre un bearer token et la signature HMAC ?
Un bearer token est envoyé à chaque requête et donne accès par possession, si bien qu'un token capturé est rejouable jusqu'à son expiration. La signature HMAC n'envoie jamais le secret — le client signe une requête canonique et n'envoie que la signature, si bien qu'une requête capturée ne peut être rejouée contre un autre appel et que l'identifiant lui-même n'est jamais exposé.
Pourquoi la signature HMAC a-t-elle besoin d'une requête canonique ?
Parce que les deux parties doivent calculer la chaîne identique pour obtenir des signatures concordantes. La requête canonique fixe exactement comment la méthode, le chemin, la requête triée, les en-têtes signés et le hash du corps sont sérialisés. Tout désaccord — ordre des en-têtes, espaces, un corps réencodé — produit une signature différente et la requête est rejetée même si rien n'a été altéré.
Que m'apporte OAuth 2.0 client-credentials par rapport à une clé d'API ?
Une courte durée de vie et un cadre explicite. Le client échange ses identifiants auprès d'un endpoint de token contre un access token à courte durée de vie et cadré (RFC 6749). Un token capturé expire vite, et un token forgé pour l'envoi ne peut administrer le compte. Une clé d'API statique, à l'inverse, est à longue durée de vie et typiquement large.
Comment les clés d'API devraient-elles être cadrées et rotatées ?
Accordez le moindre privilège — restreignez chaque clé aux opérations, sources et débit dont elle a besoin — pour qu'une fuite soit contenue. Rotatez avec chevauchement des clés : émettez un nouvel identifiant, exécutez les deux en parallèle pendant la migration des clients, puis révoquez l'ancien. Les clés devraient porter un id de clé non secret et être révocables individuellement pour qu'une intégration compromise soit coupée seule.
Quand le TLS mutuel vaut-il son coût opérationnel ?
Lorsqu'il vous faut une identité cryptographique au niveau transport pour un lien machine à machine à haute assurance, ou pour épingler un partenaire à des certificats spécifiques. Le mTLS n'admet que les clients dont le certificat X.509 remonte à une AC de confiance. Il est plus lourd à exploiter — émission, rotation, révocation — si bien qu'il est réservé aux intégrations les plus sensibles, souvent superposé d'un token ou d'une signature pour l'autorisation.
Pourquoi les identifiants bearer ne doivent-ils jamais apparaître dans une URL ou un journal ?
Parce qu'un identifiant bearer donne accès par la seule possession. Les URL sont journalisées par les proxys, stockées dans l'historique du navigateur et fuitées via l'en-tête Referer, et les journaux applicatifs sont largement lisibles, si bien qu'un token dans l'un d'eux est effectivement divulgué. Les identifiants bearer ne doivent voyager que dans l'en-tête Authorization sur TLS et être expurgés des journaux.
Spécifications sources
Les normes publiées sur lesquelles repose cette page. S'ouvre dans un nouvel onglet.