Passer au contenu principal
Permettez aux utilisateurs de se connecter avec Phaseo et de dépenser leurs propres crédits dans votre application : OAuth 2.1 avec PKCE fournit un jeton d’accès à votre serveur, et un unique proxy côté serveur l’ajoute à chaque appel au gateway. À la fin, vous disposez d’une application locale avec connexion, des jetons stockés en session qui se renouvellent, la découverte des modèles, un flux de chat sur /responses et un testeur pour les autres endpoints. L’exemple découvre les endpoints OAuth de Phaseo, vérifie state et iss au retour, renouvelle les jetons en toute sécurité et révoque la clé quand l’utilisateur se déconnecte. Pour qu’un agent de codage crée la même application de zéro, collez ce prompt :

Créer un atelier Next.js avec connexion, OAuth et un proxy Phaseo unifié.

Ouvrir dans Cursor

Comment l’exemple est construit

L’exemple se trouve dans examples/oauth-client-nextjs : Séparer la connexion des appels au gateway évite qu’un problème de connexion ressemble à un problème de modèle, et tous les endpoints partagent un seul endroit qui gère les jetons.

Lancer l’application

Il vous faut Node.js, une application OAuth dont l’URI de redirection est http://localhost:3000/auth/callback (ou votre propre callback), et un long secret de session aléatoire. Créez l’application OAuth dans Paramètres → Applications OAuth ou avec l’API des clients OAuth.
1

Installer

2

Créer .env.local

Renseignez les valeurs :L’exemple les lit toutes uniquement côté serveur. Ne mettez jamais le secret client ni le secret de session dans une variable NEXT_PUBLIC_.L’exemple trouve les endpoints d’autorisation, de jeton, de révocation et userinfo via https://api.phaseo.app/.well-known/oauth-authorization-server, et demande openid email profile gateway:access. gateway:access permet au jeton d’appeler le Gateway.
3

Démarrer le serveur de développement

Ouvrez http://localhost:3000, connectez-vous et ouvrez le tableau de bord.

Vérifier que tout fonctionne

  • La connexion revient sur votre URL de callback et crée une session.
  • Le tableau de bord liste les modèles via /api/gateway/models.
  • Un tour de chat via /api/gateway/responses reçoit une réponse, et aucune requête du navigateur ne transporte le jeton d’accès.
  • Un chemin hors de la liste d’autorisation du proxy est refusé.

Durée de vie des jetons

L’endpoint de jeton renvoie deux jetons :
  • Rotation à chaque renouvellement. Chaque renouvellement renvoie un nouveau jeton d’accès et un nouveau jeton de renouvellement. Stockez les deux et supprimez les anciens : l’ancien jeton d’accès cesse de fonctionner immédiatement, et l’ancien jeton de renouvellement ne peut plus être utilisé.
  • Renouvellement après expiration. Vous pouvez renouveler après l’expiration du jeton d’accès, tant que le jeton de renouvellement n’a pas expiré.
  • Ne réutilisez jamais un jeton de renouvellement. L’utiliser une seconde fois met fin à la connexion. Phaseo le traite comme un jeton divulgué et révoque le jeton d’accès ainsi que tous les jetons de renouvellement de cette connexion ; l’utilisateur doit alors se reconnecter.
  • Les scopes ne font que diminuer. Un renouvellement n’ajoute jamais de scope. Il conserve les scopes approuvés par l’utilisateur, moins ceux qu’il a retirés depuis.
  • Quand le renouvellement échoue. Le renouvellement échoue dès que l’utilisateur révoque votre application, révoque ou désactive sa clé, retire un scope dont la clé a besoin (comme gateway:access) ou quitte l’espace de travail. Retirer gateway:access révoque aussi la clé ; son jeton d’accès cesse donc de fonctionner immédiatement. Accorder à nouveau le scope ne rétablit pas le jeton de renouvellement. Faites repasser l’utilisateur par la connexion.
  • Se reconnecter renouvelle la clé. La connexion renouvelle la même clé au lieu d’en ajouter une, que vous envoyiez resource=https://api.phaseo.app/v1 ou non. Vous obtenez un nouveau jeton d’accès et un nouveau jeton de renouvellement, les précédents cessent de fonctionner, et la clé conserve les dépenses du mois en cours. Sa limite de dépenses mensuelle devient celle que l’utilisateur vient d’approuver. Le jeton de renouvellement d’une connexion antérieure est simplement refusé, et l’envoyer à l’endpoint de jeton ou de révocation ne met pas fin à la nouvelle connexion.
  • Une clé en pause bloque la connexion. Si l’une des clés de votre application pour cet utilisateur et cet espace de travail est en pause, quelle que soit sa ressource, l’endpoint de jeton renvoie invalid_grant jusqu’à ce que quelqu’un réactive la clé dans Paramètres → Clés API. Le renouvellement ne fonctionne que tant que la clé n’est pas révoquée : après une déconnexion ou toute autre révocation, la connexion émet une nouvelle clé, dont les limites et les dépenses repartent de zéro.
  • Déconnexion par révocation. Envoyez le jeton de renouvellement à https://api.phaseo.app/oauth/revoke. Cela révoque la clé et tous les jetons de renouvellement de la connexion, y compris celui qu’un renouvellement vient d’émettre.

Limites de dépenses

Sur l’écran de consentement, l’utilisateur fixe une limite de dépenses mensuelle pour votre application : $20.00 par défaut, un autre montant ou aucune limite. Une fois ce montant dépensé par la clé au cours d’un mois calendaire, les requêtes au gateway renvoient 429 avec key_limit_exceeded jusqu’au mois suivant ou jusqu’à ce que l’utilisateur relève la limite dans Paramètres → Clés API. Quels que soient ses scopes, votre application ne peut ni lever cette limite ni la contourner via l’API. Elle peut seulement renommer ou supprimer des clés API. Elle ne peut pas créer ni faire tourner de clés, modifier les limites, l’état ou l’expiration d’une clé, créer des clés de gestion ou des workloads de confiance, ajouter des membres, modifier les budgets, les garde-fous, les limites de débit ou les règles de dépenses, ni modifier les plafonds de prix de l’espace de travail pour le routage ou son repli BYOK vers les crédits.

Avant la mise en production

  • Réduisez la liste d’autorisation. lib/gateway.ts autorise les chemins qu’appelle l’atelier, ainsi que le statut des tâches sous videos/ et music/generate/. Ne gardez que les chemins que votre produit appelle.
  • Partagez les renouvellements entre instances. lib/oauth.ts partage en mémoire un seul renouvellement entre les requêtes parallèles. Si vous exécutez plusieurs instances du serveur, déplacez ce partage vers un stockage commun ; sinon, deux instances peuvent renouveler avec le même jeton et mettre fin à la connexion.
  • Envoyez toute la conversation. Le Gateway ne stocke pas les réponses et refuse previous_response_id ; renvoyez donc les tours précédents dans input.
  • Remplacez le testeur. Gardez l’atelier pour la QA interne et créez des parcours dédiés pour les utilisateurs finaux.
Pour une application à clé API sans connexion, partez de l’application de chat web Next.js.
Dernière modification le 13 novembre 2026