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": "measurement.scan", "maxSessions": 1 }],
  "duration": "15min"
}

Champs de la requête

Permissions

Deux permissions existent, une par chaîne de mesure.

{ "name": "measurement.scan", "maxSessions": 1 }

Ce sont deux portes distinctes : un jeton frappé pour l’une ne se fait pas accepter par l’autre. Un même jeton peut porter les deux, en les demandant toutes les deux — nommer deux fois la même reste refusé.

Une session est comptée à son ouverture, non à l’aboutissement d’une mesure — une reconnexion à une session déjà ouverte ne compte pas. 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 une durée : un nombre, une unité, et éventuellement d’autres à la suite.

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 de nouveau à l’enregistrement du jeton.
• Écrivez le plafond en heures : 48h, non 2d. Les jours sont comptés sur le calendrier à l’enregistrement du jeton, où un jour ne dure pas toujours 24 heures. Une durée en jours qui dépasse alors le plafond passe la validation mais est refusée à ce moment-là — par un 500 plutôt qu’un 400, aujourd’hui.

Réponse

201 Created

{
  "id": "8f1c2d34-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "value": "ivat-GPPctPJ3HURBcwEKJFq26Ckp4khJUeNp8qjhLK0RblozlBfP0",
  "description": "Mobile application, iOS and Android",
  "permissions": [{ "name": "measurement.scan", "maxSessions": 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, avec un corps vide. 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": "measurement.scan", "maxSessions": 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é à 20 appels par minute et par clé d’API, plus serré que les 300 généraux. Émettez un jeton par mesure, au moment où la mesure démarre.