Clés d’API, scopes et contraintes de plateforme
Chaque requête, sur l’une ou l’autre API, est authentifiée par une clé, et chaque clé porte des scopes qui déterminent ce qu’elle peut faire. Dans la requête, les deux API diffèrent — un en-tête d’un côté, un segment de chemin de l’autre — mais leurs clés sont émises, vérifiées et retirées par le même système sous-jacent.
Avant de lire cette page
Le démarrage rapide a déjà placé un jeton Bearer dans un en-tête de requête, sans expliquer sa structure ni ce qu’il est autorisé à faire — cette page comble ce manque. Revoir la première requête API
La structure d’un jeton v3
Une clé v3 est envoyée comme un jeton Bearer standard, avec un préfixe fixe qui l’identifie comme une clé Livstick, avant la partie secrète :
Authorization: Bearer liv_<prefix>_<secret>- liv_ signale d’un coup d’œil que le jeton est une clé Livstick, dans les logs comme dans les tickets de support.
- <prefix> identifie la clé sans exposer le secret — il peut être journalisé ou affiché sans risque.
- <secret> est la partie qui authentifie la requête, et la seule qui doit rester confidentielle.
Les neuf scopes v3
Une clé v3 reçoit un ou plusieurs des neuf scopes. Chaque scope correspond à un pan des fonctionnalités liées aux conteneurs et aux messages, pas à un endpoint unique — containers:read, par exemple, couvre à la fois la liste des conteneurs et la lecture d’un conteneur.
| Scope | Autorise |
|---|---|
| containers:read | Lister les conteneurs, lire un conteneur et récupérer ses URL d’enregistrement et d’aperçu. |
| containers:write | Créer ou récupérer un conteneur, et le corriger par une mise à jour partielle. |
| containers:notify | Déclencher la remise au destinataire. |
| containers:unlock | Rendre un message accessible à son destinataire. |
| containers:qrcode | Récupérer le QR code du conteneur au format PNG. |
| containers:card | Récupérer la carte imprimable du conteneur au format PDF. |
| messages:read | Lire les messages, filtrés par identifiant de conteneur ou par groupe de codes. |
| messages:write | Mettre à jour les champs data et privateData d’un message. |
| code_groups:read | Lire la liste des groupes de codes. |
Quatre scopes ajoutés pour l’API v3.1
L’API v3.1 reprend les scopes containers:* et messages:read listés ci-dessus, pour les mêmes opérations, et en ajoute quatre. Une clé qui doit appeler l’une des nouvelles routes a besoin du scope correspondant dès sa création : un scope ne peut pas être ajouté à une clé existante ; créez donc une nouvelle clé et retirez l’ancienne.
| Scope | Autorise |
|---|---|
| tokens:record | Émettre des jetons d’enregistrement, qui permettent au widget d’enregistrement d’écrire un message pour un mrid. |
| tokens:view | Émettre des jetons de visualisation, qui permettent au widget de lecture de lire un message ou un conteneur entier. |
| messages:publish | Libérer un message retenu, et supprimer un message en cas de remboursement ou de rétractation. |
| webhooks:read | Lire le journal des envois de votre plateforme. |
Les deux scopes 2.1
L’API 2.1 ne découpe pas les permissions par opération comme le fait la v3. Elle accorde l’accès par famille de routes, avec un scope par famille : client_v2 pour les routes /v2.1/client/… destinées au client, user_v2 pour la route /v2.1/user/… destinée au destinataire.
| Scope | Autorise |
|---|---|
| client_v2 | Toutes les routes /v2.1/client/{key}/{crid}/… : redirect, retarget, QR code, carte, notify, modify, details, enregistrement de webhook. |
| user_v2 | La route /v2.1/user/{key}/{crid}/redirect destinée au destinataire. |
Un seul système de clés pour les deux API
C’est le point à retenir : la v3 et la 2.1 ne sont pas deux systèmes d’authentification accolés l’un à l’autre. Une clé — quelle que soit l’API qu’elle cible — est gérée par la même infrastructure sous-jacente.
- Les secrets sont stockés hachés, jamais sous une forme qui permettrait de les relire.
- Une clé peut avoir une date d’expiration, et son statut (active, revoked, expired) est vérifié à chaque requête.
- Chaque utilisation est auditée, et lastUsedAt est tenu à jour pour chaque clé.
- Une clé peut être restreinte à une plateforme, en plus de ses scopes.
Où voir vos scopes réels
Cette page recense ce qui existe — chaque scope défini par l’une ou l’autre API, et la structure d’une clé. Elle ne vous dit pas, et ne peut pas vous dire, quels scopes détiennent vos propres clés, ni vous montrer la valeur réelle d’une clé.