Jetons d'accès

Un jeton d’accès est ce que vous remettez à un navigateur à la place de votre clé d’API. Il nomme ce qu’il a le droit de faire, il expire, et vous pouvez le rendre à usage unique.

Créer un jeton

POST /access-tokens
Authorization: Bearer <apiKey>
Content-Type: application/json

{
  "description": "Mobile application, iOS and Android",
  "permissions": [{ "name": "websocket.measurement", "maxAttempts": 1 }],
  "duration": "15min"
}

Champs de la requête

Permissions

Une seule permission existe aujourd’hui.

{ "name": "websocket.measurement", "maxAttempts": 1 }

Une tentative est consommée par l’ouverture d’une session, non par l’aboutissement d’une mesure. Un utilisateur qui ouvre la caméra puis s’en va a consommé le jeton. C’est pourquoi le widget en demande un nouveau au début de chaque tentative plutôt que de le mettre en cache.

Durées

duration s’écrit comme un intervalle — un nombre, une unité, éventuellement répétés :

30s          15min        2h           48h
2h 30min     1d           1d 12h

Unités acceptées :

Deux règles supplémentaires :

• Une unité ne peut apparaître qu’une fois, toutes ses orthographes comptant comme la même unité. 1d 12h est valide ; 1d 1day ne l’est pas.
• Le plafond est de 48 heures. Un jeton existe pour la mesure qu’il ouvre, non pour la durée d’un contrat. Il est imposé à la fois lors de la validation de votre requête et sur la table elle-même.

Réponse

201 Created

{
  "id": "8f1c2d34-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "value": "ivat-XCq7mR4vT8pLnW2yZbJ6sD9eA1gUiO5rN0kMxPq7Yt",
  "description": "Mobile application, iOS and Android",
  "permissions": [{ "name": "websocket.measurement", "maxAttempts": 1 }],
  "expiresAt": "2026-08-24T15:12:44.000Z",
  "createdAt": "2026-08-24T14:57:44.000Z"
}

expiresAt vaut exactement createdAt plus la durée demandée, résolue par la base de données plutôt que par votre horloge ou par la nôtre.

Révoquer un jeton

DELETE /access-tokens/{id}
Authorization: Bearer <apiKey>

200 OK en cas de succès. Le {id} est l’id de la réponse de création — non value.

Un jeton expiré reste supprimable. L’expiration masque un jeton à toute lecture, mais elle ne retire pas la ligne, et faire le ménage derrière soi reste possible.

Exemple complet

Les commandes ci-dessous s’adressent à la Production. Les mêmes appels sur le Test ne diffèrent que par la base :

Un jeton émis sur l’un n’est jamais valable sur l’autre — voir Environnements.

# Émettre un jeton à usage unique, valable un quart d'heure
curl -sX POST https://api.saphere.ai/access-tokens \
  -H "Authorization: Bearer $SAPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "description": "web widget",
        "permissions": [{ "name": "websocket.measurement", "maxAttempts": 1 }],
        "duration": "15min"
      }'

# Le révoquer par anticipation
curl -sX DELETE https://api.saphere.ai/access-tokens/8f1c2d34-5a6b-4c7d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer $SAPHERE_API_KEY"

Quand un jeton est refusé

Le serveur de mesure refuse une poignée de main sans dire pourquoi — délibérément, pour qu’un jeton rejeté ne puisse pas être sondé pour en connaître le motif. Déroulez la liste :

Limite de débit

POST /access-tokens est limité à 10 appels par minute et par clé d’API, plus serré que les 120 généraux. Émettez un jeton par mesure, au moment où la mesure démarre.