Jetons d'accès
Une session, un jeton, frappé par votre serveur et consommé par la poignée de main.
Une session s’ouvre en présentant un jeton d’accès, dans l’adresse de la poignée de main :
https://api-webtransport.<hôte de votre environnement>/measures?accessTokenValue=<jeton>&visual=video-full&format=webm
Il voyage dans l’adresse plutôt que dans un en-tête parce qu’une poignée de main WebTransport n’en porte aucun — c’est l’interface, et elle est la même pour tout le monde. Deux conséquences en découlent, et ce sont elles qui font le jeton tel qu’il est : une adresse s’écrit dans plus d’endroits qu’un en-tête, donc frappez-en un par session et limitez sa durée à l’intervalle qui sépare la décision de mesurer de la poignée de main elle-même.
Votre serveur le frappe
Votre serveur détient la clé d’API et appelle POST /access-tokens avec la permission measurement.realtime :
{
"permissions": [{ "name": "measurement.realtime", "maxSessions": 1 }],
"duration": "15min"
}
maxSessions: 1 mérite d’être écrit explicitement : le champ est facultatif, et une borne absente veut dire sans limite — un jeton rejouable pendant toute sa durée, alors qu’il voyage dans une adresse.
La réponse porte value, montré une fois et jamais plus : l’API n’en garde qu’un condensé. C’est cette chaîne que prend la poignée de main, et id — que la même réponse porte — n’ouvre rien ; c’est ce qui révoque le jeton.
La clé d’API reste sur votre serveur
Elle est de longue durée, sans portée, et ouvre toutes les routes de l’API. Un jeton est son contraire : une chaîne, une session, quelques minutes de vie. Rien de ce qui atteint un client ne doit être autre chose qu’un jeton.Depuis la librairie de navigateur
La librairie ne détient aucun jeton : elle vous en demande un, par retrieveAccessToken, et elle le demande à chaque start() — un jeton est à usage unique, et la poignée de main le consomme. Rien n’est mis en cache, et c’est pourquoi l’option est un rappel plutôt qu’une valeur. Chaque démarrage demande donc un jeton frappé de votre côté, et POST /access-tokens est limité à 20 appels par minute et par clé d’API.
RealtimeMeasure.create({
video: "#camera",
retrieveAccessToken: () => fetch("/mon-serveur/realtime-token").then(response => {
if (!response.ok)
throw new Error(`HTTP ${response.status}`)
return response.text()
})
})
Testez response.ok : la librairie ne vérifie que la réception d’une chaîne non vide, si bien que le texte d’une réponse d’erreur serait pris pour un jeton, et refusé à la poignée de main.
Rendez la chaîne, ou une promesse de chaîne. Tout le reste — un rejet, une exception, aucune réponse en dix secondes, ou une réponse qui n’est pas une chaîne non vide — fait échouer le démarrage, et token:error dit laquelle :
reason | Ce qui s’est passé |
|---|---|
no-callback | Aucun retrieveAccessToken n’a été donné. La librairie ne peut pas mesurer sans lui. |
strategy-failed | Votre rappel a levé, a rejeté, ou est resté muet dix secondes. |
unusable-response | Il a répondu autre chose qu’une chaîne non vide. |
La valeur du jeton ne voyage sous aucun événement, et ne figure dans aucune charge que la librairie vous remet. Si votre endpoint relaie la réponse de l’API, prenez-y value — id n’ouvre rien, c’est ce qui révoque.
À quoi ressemble un refus
La poignée de main consomme le jeton — le résoudre, c’est le dépenser —, si bien qu’une session ouverte puis abandonnée en a dépensé un tout de même. Avec maxSessions: 1, une seconde poignée de main demande un second jeton, ce qui fait d’une reprise automatique une décision et non un geste gratuit.
Un jeton absent, malformé, expiré, déjà dépensé, révoqué, frappé pour l’autre chaîne ou dont le compte a été désactivé est refusé en 401, et la session ne s’ouvre pas : le client voit sa promesse ready échouer, sans rien de plus précis. C’est délibéré — un refus qui dirait lequel de ces cas il est répondrait à des questions que personne de légitime ne pose — et ce sont donc vos propres journaux, côté frappe, qui les distinguent. Les autres refus de la poignée de main — une déclaration que le serveur ne sait pas servir, un serveur à pleine capacité, et un 403 quand la mesure temps réel n’est pas disponible sur votre compte (la frappe du jeton, elle, ne proteste pas) — sont listés sur la page du format de fil, et aucun d’eux ne dépense le jeton : ils sont tranchés avant qu’il ne soit consommé. Depuis la librairie, chacun de ces refus se voit comme un realtime:error suivi d’un start() rejeté ; token:error ne sert que pour un jeton que votre rappel n’a pas pu livrer.
Une permission par chaîne
measurement.realtime ouvre une session temps réel et rien d’autre. Un jeton frappé avec measurement.scan — la chaîne de Saphere Scan — est refusé ici, et l’inverse aussi.