← Guides pour développeurs

Choisissez votre mode d'authentification

Deux façons d'authentifier le SDK — un arbre de décision pour savoir si vous avez besoin d'une clé API statique ou d'un session JWT par utilisateur.

Le SDK prend en charge deux modes d’authentification. Choisir le bon dépend de l’endroit où s’exécute réellement le code qui appelle le SDK — pas de ce qui est le plus pratique.

L’arbre de décision

Ce code s’exécute-t-il sur votre serveur (backend Node.js, cron job, service interne) ? → Le mode clé API est disponible. Passez votre clé en tant qu’apiKey. Générez-en une en libre-service depuis la page de détail de votre application dans la Console (Regenerate API Key) — voir Obtenez votre clé API — ou utilisez le mode session JWT ci-dessous si vous préférez ne pas gérer de clé statique.

const ai = new Quravin({
  endpoint: process.env.QURAVIN_URL,
  apiKey:   process.env.QURAVIN_KEY,   // depuis votre gestionnaire de secrets — ne jamais committer
});

Ce code s’exécute-t-il dans le navigateur d’un utilisateur ? → Utilisez le mode session JWT. Votre serveur crée un token de courte durée, propre à chaque utilisateur, et le transmet à la page — le navigateur ne voit jamais client_secret ni une clé API statique.

const ai = new Quravin.Quravin({
  endpoint: "https://api.quravin.com",
  sessionToken: await fetchToken(),   // depuis votre propre endpoint backend
  onTokenExpired: fetchToken,          // rafraîchissement automatique sur 401
});

x-api-key contre session JWT — ils ne sont pas interchangeables

L’apiKey ci-dessus envoie la requête en tant que x-api-key: <key>. Il s’agit d’un identifiant hérité, au niveau de l’application, non rattaché à une organisation, que la plateforme est en train de remplacer progressivement par des JWT par utilisateur. Deux choses à savoir avant d’y recourir :

• Pas de portefeuille d’organisation. Si votre compte est en facturation par portefeuille (wallet-mode billing), un appel facturable POST /tickets authentifié avec une x-api-key nue retourne 402 insufficient_credits, même si le portefeuille de votre organisation dispose de fonds — la clé n’est rattachée à aucune organisation, elle ne peut donc pas dépenser depuis l’une d’elles. C’est voulu, pas un bug.
• Pas d’identité par utilisateur. Chaque appel semble provenir de « l’application », pas d’un utilisateur en particulier — adapté pour un cron job, mais pas si vous avez besoin d’un audit/d’une attribution par utilisateur ou d’une liste d’autorisation pipelines[] plus stricte que celle de toute l’application.

Si la facturation ou l’attribution par utilisateur compte le moindrement, utilisez le mode session JWT — créez-le via POST /auth/token, pas via x-api-key. Si plusieurs tenants ou clients partagent le même processus backend ou le même identifiant, utilisez aussi le mode session JWT — il limite chaque appelant à ses propres tickets, contrairement à un simple x-api-key.

Créer un session JWT : POST /auth/token

Votre backend crée un JWT de courte durée par utilisateur en appelant l’endpoint POST /auth/token de la plateforme, en s’authentifiant avec la paire client_id/client_secret obtenue dans Obtenez votre clé API, utilisée comme authentification HTTP Basic :

curl -X POST "https://api.quravin.com/auth/token" \
  -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "user-12345",
    "pipelines": ["translate-string"],
    "ttl_seconds": 900
  }'

Réponse :

{ "token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 900 }

• subject (obligatoire) — l’identifiant de cet utilisateur dans votre application ; devient le sub du JWT.
• pipelines (optionnel) — la liste d’autorisation (ACL) que vous voulez pour ce token. Un utilisateur ne peut appeler que les pipelines listés dans le allowed_pipelines de votre Application (défini dans la Console, voir Obtenez votre clé API) — ce que vous demandez ici est croisé avec cette liste d’autorisation côté serveur, donc vous ne pouvez pas accorder à un utilisateur plus que ce que votre application elle-même est autorisée à faire. Omettez ce champ pour obtenir un token portant la liste d’autorisation complète de votre application.
• ttl_seconds (optionnel) — durée de vie du token, plafonnée entre 60 et 3600 secondes, 900 par défaut (15 min).

Transmettez le token retourné au navigateur en tant que sessionToken. Voir Intégrez dans votre propre serveur pour l’endpoint complet et le câblage côté navigateur, ainsi que pour l’alternative héritée d’auto-signature, qui utilise un signing secret fourni séparément au lieu de client_id/client_secret.

Pourquoi c’est important

Une clé API statique est un identifiant porteur — quiconque la lit dans le code source de votre page a un accès complet à tout ce que votre application peut faire. Un session JWT est propre à un seul utilisateur, expire en quelques minutes, porte une liste d’autorisation pipelines[], et est généré à nouveau par votre serveur à chaque chargement de page.

Règle empirique : si le code est livré dans un navigateur, ou si la facturation/l’attribution par utilisateur compte, il a besoin d’un session JWT, pas d’une clé API statique.

Suivant : Intégrez dans votre propre serveur montre l’endpoint de création de token qui délivre les session JWT.