/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é.
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 esthttp://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
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
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/responsesreç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. Retirergateway:accessré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/v1ou 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_grantjusqu’à 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 renvoient429 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.tsautorise les chemins qu’appelle l’atelier, ainsi que le statut des tâches sousvideos/etmusic/generate/. Ne gardez que les chemins que votre produit appelle. - Partagez les renouvellements entre instances.
lib/oauth.tspartage 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 dansinput. - Remplacez le testeur. Gardez l’atelier pour la QA interne et créez des parcours dédiés pour les utilisateurs finaux.