> ## Documentation Index > Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request. > Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance. > For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code. > The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust. > Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool. > Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md. # Build an OAuth Next.js Workbench > Use the full OAuth Next.js example as a walkthrough for a signed-in gateway app with a unified proxy. Use this page when your product needs sign-in, session-backed gateway access, and more than a single chat route. **Goal:** Run the signed-in workbench and send Phaseo requests through one protected server-side proxy. **Outcome:** A local application with OAuth sign-in, session-backed tokens, model discovery, chat, and an endpoint tester. Build a **signed-in Next.js workbench** with OAuth and a unified Phaseo proxy. You are building a signed-in Next.js app on top of Phaseo Gateway. Create a workbench-style app with: \- OAuth 2.1 + PKCE sign-in \- session-backed token storage \- one unified gateway proxy route on the server \- model discovery \- one chat flow using the Responses API \- one generic endpoint tester for additional Phaseo endpoints Requirements: \- Keep gateway credentials and access tokens server-side. \- Use a proxy allowlist for safety. \- Support token refresh. \- Keep the workbench understandable rather than over-engineered. \- Add a short README with setup, env vars, and run steps. Verification: \- run the app if possible \- verify sign-in flow as far as local setup allows \- verify at least one proxied gateway request path \- report exactly what you verified and what remains dependent on external OAuth configuration. ## Sample project * GitHub: [examples/oauth-client-nextjs](https://github.com/phaseoteam/Phaseo/tree/main/examples/oauth-client-nextjs) * Local repo path: `examples/oauth-client-nextjs` ## What this app covers * OAuth 2.1 + PKCE login * session-backed token storage and refresh * a unified proxy for control and generation routes * model discovery * a chat flow over `/responses` * a generic endpoint tester for other gateway routes ## When to start with this example Use this when: * end users should sign in with delegated access * you need more than a simple chat page * you want one secure server route for several Phaseo endpoints Do not start here if: * you only need a simple API-key chat UI * you want a script or CLI first ## Key files * app/ * page.tsx * dashboard/ * page.tsx * GatewayWorkbench.tsx * api/ * gateway/ * \[...surface]/ * route.ts * lib/ * oauth.ts * session.ts ## Why the sample is structured this way ### 1. OAuth stays separate from gateway logic The app isolates: * auth start and callback logic * encrypted session handling * token refresh That keeps the AI integration code simpler and makes sign-in issues easier to debug. ### 2. One proxy route handles the gateway calls The catch-all proxy route: * checks the endpoint allowlist * injects the current bearer token * refreshes tokens when needed * forwards request and response bodies This is a good pattern when you want several Phaseo endpoints without copying auth logic into every route. ### 3. The dashboard doubles as an internal workbench The workbench page is not only chat: * it discovers models * it exercises `/responses` * it can test non-chat endpoints too That makes it useful for onboarding, QA, and internal debugging before you build a more polished end-user UI. ## Prerequisites * Node.js and one supported package manager * an OAuth client configured with the local callback URL * a strong session secret ## Run the sample ```bash npm theme={null} cd examples/oauth-client-nextjs npm install cp .env.example .env.local ``` ```bash pnpm theme={null} cd examples/oauth-client-nextjs pnpm install cp .env.example .env.local ``` ```bash yarn theme={null} cd examples/oauth-client-nextjs yarn install cp .env.example .env.local ``` ```bash bun theme={null} cd examples/oauth-client-nextjs bun install cp .env.example .env.local ``` Set: * `NEXT_PUBLIC_OAUTH_CLIENT_ID` * `OAUTH_CLIENT_SECRET` * `NEXT_PUBLIC_PHASEO_URL` * `NEXT_PUBLIC_REDIRECT_URI` * `SESSION_SECRET` * `NEXT_PUBLIC_GATEWAY_URL` Then run: ```bash npm theme={null} npm run dev ``` ```bash pnpm theme={null} pnpm dev ``` ```bash yarn theme={null} yarn dev ``` ```bash bun theme={null} bun run dev ``` Open `http://localhost:3000`. ## Check your work * Sign-in returns to the configured callback and creates a session. * The dashboard can discover models through the proxy. * One Responses API request completes without exposing an access token to the browser. * An endpoint outside the proxy allowlist is rejected. ## How to make it your own * trim the proxy allowlist to the endpoints your product really needs * keep the workbench internally while building a cleaner user-facing UI on top * swap the generic tester for purpose-built product flows once the integration stabilizes ## Related guides * [Build a Next.js web chat app](https://phaseo.app/docs/v1/cookbook/build-a-nextjs-web-chat-app.md) * [Mini app starter prompts](https://phaseo.app/docs/v1/cookbook/mini-app-starter-prompts.md) * [Examples](https://phaseo.app/docs/v1/guides/examples.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.