Authentification

Les deux identités que porte chaque appel Fleeex : la clé d'API de votre application et l'identifiant de l'utilisateur final dont vous vous portez garant.

Chaque appel émis par le SDK porte deux identités. Les poser correctement est ce qui rend le comptage juste et propre à chaque utilisateur.

const client = new FleeexClient({
  apiKey: process.env.FLEEEX_API_KEY!, // flx_…
  userId: "user-123",
});

La clé d'API (flx_…)

• Elle authentifie votre application. Émettez et faites tourner vos clés depuis votre compte Fleeex (le tableau de bord, ou plan de contrôle).
• C'est un secret côté serveur. Une clé fuitée usurpe votre application : ne l'embarquez jamais dans un navigateur, un bundle mobile ou un dépôt public. Gardez-la dans une variable d'environnement ou un gestionnaire de secrets.

Une clé est émise pour l'un de deux mondes, choisi à l'émission et jamais modifié. Une clé live (flx_…) dépense de l'argent réel ; une clé de test (flx_test_…) dépense un solde fictif et n'appelle aucun fournisseur de modèle. Le préfixe vous dit laquelle, et aucun geste ne promeut l'une en l'autre. Voir Bac à sable.

L'identifiant utilisateur (x-fleeex-user)

• C'est votre propre identifiant pour l'utilisateur final, celui que votre application emploie déjà. Fleeex fait confiance à votre application pour l'identité de ses propres utilisateurs, et l'identifiant ne franchit jamais la frontière de votre application.
• C'est aussi ce qui rend l'usage et la facturation propres à chaque utilisateur : chaque couple (app, utilisateur) correspond à une identité de portefeuille.

Cette valeur entre dans une clé de stockage, elle est donc bornée. Envoyez quelque chose qui tient dans ces limites, sinon la requête est un 400 qui nomme la règle (et ne renvoie jamais votre valeur en écho) :

Un e-mail (254 caractères au plus), un UUID ou n'importe quel identifiant opaque de fournisseur tiennent largement.

Quelles routes l'exigent : le proxy, getBalance(), getConnection() et getUsageSummary() l'exigent tous, et répondent leur propre 400 en son absence. GET /v1/models ne l'exige délibérément pas, car le catalogue est une propriété de votre application et non de l'un de ses utilisateurs finaux : un client peut donc énumérer les modèles avant même d'avoir un utilisateur. Voir Choisir un modèle.

Un FleeexClient est lié à un seul userId. Vous gérez beaucoup d'utilisateurs ? Créez un client par utilisateur (ils sont peu coûteux), ou posez l'en-tête requête par requête avec le SDK OpenAI brut (voir Revenir au SDK OpenAI brut).

Plan de contrôle et plan de données

Le SDK travaille sur le plan de données : appels IA relayés et aides de facturation en lecture seule, authentifiés par la clé d'API de l'application. La gestion du compte lui-même (approvisionner le portefeuille, créer des applications, émettre des clés) relève d'un plan de contrôle distinct, le tableau de bord. Une clé d'application peut donc dépenser sur un portefeuille, mais jamais le recharger ni créer de nouvelles clés.

Tracer un appel

Chaque réponse porte un x-correlation-id, et le même identifiant apparaît dans l'enveloppe d'erreur. Envoyez le vôtre pour relier un appel Fleeex à une requête dans vos propres journaux :

const client = new FleeexClient({
  apiKey,
  userId,
  defaultHeaders: { "x-correlation-id": requestId },
});

C'est la seule prise qui relie une panne que vous avez constatée à sa trace côté serveur : journalisez-la chaque fois que vous attrapez une erreur.

Votre valeur n'est conservée que si elle fait au plus 64 caractères pris dans A–Z a–z 0–9 _ . : - ; sinon elle est remplacée en silence par un identifiant neuf. Relisez donc l'identifiant sur la réponse plutôt que de supposer que le vôtre a été retenu. Un UUID ou un identifiant de trace conviennent ; une URL ou un blob JSON, non.

Ensuite

• Démarrage rapide : faites un appel.
• Choisir un modèle : quels modèles votre application peut appeler.
• Solde et paiements : lisez le solde et gérez le parcours de rechargement du 402.