Saltar al contenido principal
Permite que las personas inicien sesión con Phaseo y gasten sus propios créditos en tu aplicación: OAuth 2.1 con PKCE le da a tu servidor un token de acceso, y un único proxy del lado del servidor lo adjunta a cada llamada al Gateway. Al terminar tendrás una aplicación local con inicio de sesión, tokens guardados en la sesión que se renuevan, descubrimiento de modelos, un flujo de chat sobre /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.

Abrir en Cursor

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 con http://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

Rellena los valores: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

Abre 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/responses recibe 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. Quitar gateway:access tambié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_grant hasta 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 devuelven 429 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.ts permite las rutas que llama el banco de trabajo, además del estado de los trabajos bajo videos/ y music/generate/. Conserva solo las rutas que llama tu producto.
  • Comparte las renovaciones entre instancias. lib/oauth.ts comparte 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 en input.
  • Sustituye el probador. Conserva el banco de trabajo para QA interno y crea flujos específicos para los usuarios finales.
Para una aplicación con clave de API y sin inicio de sesión, empieza por la aplicación de chat web con Next.js.
Última modificación el 13 de noviembre de 2026