QuavernQuavsit

Section 02 sur 12

Authentification

Chaque requête, sauf GET /health et GET /status, porte une clé personnelle dans l'en-tête Authorization.

Clés Bearer#

sh
curl -sS "https://api.quavern.net/v1/networks/tbm" \
  -H "Authorization: Bearer qv_p_…"

Les clés sont émises par myQuavern pour le service quavsit. Elles sont affichées une seule fois à la création, stockées sous forme de hash, nommées pour votre propre suivi et révocables à tout moment depuis my.quavern.com/account/quavsit. Le nombre de clés actives dépend du plan (2 en Free, 5 en Pay as you go et Starter, 20 en Pro, 50 en Max) ; en créer une de plus renvoie 409 key_limit_reached sur l'API de compte.

Scopes et audience#

Une clé Quavsit a pour audience api.quavern.net et le scope transit:read, qui couvre tous les endpoints de lecture de cette API. Le scope optionnel account:read permet à la même clé de lire GET /v1/me sur api.quavern.ai (plan, résumé d'usage) ; il n'ajoute rien sur api.quavern.net. Les scopes sont choisis à la création et ne peuvent pas être élargis ensuite ; créez une nouvelle clé.

Ce qui n'est pas accepté#

  • Les tokens de session navigateur de myQuavern, de Marl ou d'une autre application Quavern. Ils sont refusés avec 401 invalid_token.
  • Les clés émises pour un autre service (par exemple une clé Marl d'audience api.quavern.ai) : 403 insufficient_scope.
  • Les tokens de service d'organisation : Quavsit ne propose que des plans personnels dans cette version.
  • Les clés d'un compte dont l'e-mail n'est pas vérifié : 403 email_verification_required.

Endpoints publics#

GET /v1/health et GET /v1/status ne demandent pas de clé et ne sont pas comptabilisés. Tout le reste, sans clé valide, renvoie 401 authentication_required.

Erreurs rencontrées#

StatutreasoncodeSignification
401authentication_requiredSCTY3-1401pas d'en-tête Authorization
401invalid_tokenSCTY3-2401token inconnu, révoqué, expiré ou du mauvais type
403insufficient_scopeSCTY3-2403mauvaise audience, scope transit:read absent, ou clé non personnelle
403email_verification_requiredMAIL3-1403e-mail du compte non vérifié

Protéger ses clés#

N'envoyez les clés qu'en HTTPS et seulement depuis du code que vous contrôlez (un backend, un script, un outil en ligne de commande). Une clé retrouvée dans un dépôt public ou dans du code navigateur doit être révoquée et remplacée. Chaque clé rapporte son usage quotidien sur la page de compte ; une clé par application rend une fuite plus facile à repérer et moins coûteuse à corriger.