/responses y un probador para otros endpoints.
El ejemplo descubre los endpoints OAuth de Phaseo, comprueba state e iss a la vuelta, renueva los tokens de forma segura y revoca la clave cuando la persona cierra sesión.
Para que un agente de programación cree la misma aplicación desde cero, pega este prompt:
Crea un banco de trabajo de Next.js con inicio de sesión, OAuth y un proxy unificado de Phaseo.
Cómo está construido el ejemplo
El ejemplo está en examples/oauth-client-nextjs:
Separar el inicio de sesión de las llamadas al Gateway hace que un problema de inicio de sesión nunca parezca un problema del modelo, y que todos los endpoints compartan un único lugar que gestiona los tokens.
Ejecútalo
Necesitas Node.js, una aplicación OAuth conhttp://localhost:3000/auth/callback (o tu propio callback) como URI de redirección y un secreto de sesión largo y aleatorio. Crea la aplicación OAuth en Configuración → Aplicaciones OAuth o con la API de clientes OAuth.
1
Instala
2
Crea .env.local
El ejemplo las lee todas solo en el servidor. Nunca pongas el secreto de cliente ni el secreto de sesión en una variable
NEXT_PUBLIC_.El ejemplo encuentra los endpoints de autorización, token, revocación y userinfo en https://api.phaseo.app/.well-known/oauth-authorization-server, y pide openid email profile gateway:access. gateway:access permite que el token llame al Gateway.3
Inicia el servidor de desarrollo
http://localhost:3000, inicia sesión y abre el panel.Comprueba que ha funcionado
- El inicio de sesión vuelve a tu URL de callback y crea una sesión.
- El panel lista los modelos a través de
/api/gateway/models. - Un turno de chat a través de
/api/gateway/responsesrecibe respuesta, y ninguna solicitud del navegador lleva el token de acceso. - Una ruta fuera de la lista permitida del proxy se rechaza.
Duración de los tokens
El endpoint de token devuelve dos tokens:- Rota en cada renovación. Cada renovación devuelve un token de acceso nuevo y un token de renovación nuevo. Guarda los dos y descarta los anteriores: el token de acceso anterior deja de funcionar al momento y el token de renovación anterior no se puede volver a usar.
- Renueva después de la caducidad. Puedes renovar cuando el token de acceso ya ha caducado, siempre que el token de renovación no lo haya hecho.
- Nunca reutilices un token de renovación. Usarlo una segunda vez termina el inicio de sesión. Phaseo lo trata como un token filtrado y revoca el token de acceso y todos los tokens de renovación de ese inicio de sesión, así que la persona tiene que volver a iniciar sesión.
- Los scopes solo se reducen. Una renovación nunca añade scopes. Conserva los scopes que aprobó la persona, menos los que haya quitado desde entonces.
- Cuándo falla la renovación. La renovación falla cuando la persona revoca tu aplicación, revoca o desactiva su clave, quita un scope que la clave necesita (como
gateway:access) o sale del espacio de trabajo. Quitargateway:accesstambién revoca la clave, así que su token de acceso deja de funcionar al momento. Volver a conceder el scope no recupera el token de renovación. Haz que la persona vuelva a iniciar sesión. - Volver a iniciar sesión renueva la clave. Renueva la misma clave en lugar de añadir otra, envíes o no
resource=https://api.phaseo.app/v1. Obtienes un token de acceso y un token de renovación nuevos, los anteriores dejan de funcionar y la clave conserva el gasto de este mes. Su límite de gasto mensual pasa a ser el que la persona acaba de aprobar. El token de renovación de un inicio de sesión anterior simplemente se rechaza, y enviarlo al endpoint de token o de revocación no termina el nuevo inicio de sesión. - Una clave en pausa bloquea el inicio de sesión. Si cualquiera de las claves de tu aplicación para esa persona y ese espacio de trabajo está en pausa, sea cual sea su recurso, el endpoint de token devuelve
invalid_granthasta que alguien vuelva a activar la clave en Configuración → Claves de API. La renovación solo funciona mientras la clave no esté revocada: después de cerrar sesión o de cualquier otra revocación, iniciar sesión emite una clave nueva, y sus límites y su gasto empiezan de cero. - Cierra sesión con la revocación. Envía el token de renovación a
https://api.phaseo.app/oauth/revoke. Eso revoca la clave y todos los tokens de renovación del inicio de sesión, incluido uno que una renovación haya emitido un momento antes.
Límites de gasto
En la pantalla de consentimiento, la persona fija un límite de gasto mensual para tu aplicación: $20.00 por defecto, otro importe o sin límite. Cuando la clave lo ha gastado en un mes natural, las solicitudes al Gateway devuelven429 con key_limit_exceeded hasta el mes siguiente o hasta que la persona suba el límite en Configuración → Claves de API.
Tenga los scopes que tenga, tu aplicación no puede quitar ese límite ni saltárselo a través de la API. Solo puede renombrar o eliminar claves de API. No puede crear ni rotar claves, cambiar los límites, el estado o la caducidad de una clave, crear claves de gestión ni cargas de trabajo de confianza, añadir miembros, cambiar presupuestos, guardrails, límites de frecuencia ni reglas de gasto, ni cambiar los límites de precio del espacio de trabajo para el enrutamiento ni su alternativa de BYOK a créditos.
Antes de publicarlo
- Reduce la lista permitida.
lib/gateway.tspermite las rutas que llama el banco de trabajo, además del estado de los trabajos bajovideos/ymusic/generate/. Conserva solo las rutas que llama tu producto. - Comparte las renovaciones entre instancias.
lib/oauth.tscomparte en memoria una sola renovación entre solicitudes paralelas. Si ejecutas más de una instancia del servidor, lleva eso a un almacenamiento compartido; si no, dos instancias pueden renovar con el mismo token y terminar el inicio de sesión. - Envía la conversación completa. El Gateway no guarda las respuestas y rechaza
previous_response_id, así que reenvía los turnos anteriores eninput. - Sustituye el probador. Conserva el banco de trabajo para QA interno y crea flujos específicos para los usuarios finales.