setPrompt(e.target.value)} />
      <button type="button" onClick={() => void send()} disabled={running}>
        {running ? "Streaming…" : "Send"}
      </button>
      <pre>{answer}</pre>
    </div>
  );
}
```

That is the whole loop. Three things carry it:

* `listModels()` doubles as the session check. A `ChatGPTProxyError` with
  status 401 means nobody is signed in, so the page swaps to the widget.
* `streamText({ model: chatgpt(model), prompt })` goes to your
  `/api/chatgpt/responses` proxy. The browser never sees a token.
* `result.textStream` is an async iterable of text deltas. Appending them to
  state is all the streaming UI you need to start.

## Add a Fast toggle and thinking level [#add-a-fast-toggle-and-thinking-level]

Both are request headers the server validates. Wire them to two selects and
pass them into `streamText`:

```tsx
const result = streamText({
  model: chatgpt(model),
  prompt,
  headers: {
    ...(fast ? { "x-login-with-chatgpt-service-tier": "fast" } : {}),
    "x-login-with-chatgpt-reasoning-effort": thinking, // "low" | "medium" | "high"
  },
});
```

Only show the Fast toggle for models that support it, and say that it burns
included usage faster. Details in
[Fast tier & thinking effort](fast-and-reasoning.mdx).

## Or run the finished version [#or-run-the-finished-version]

The repo ships the full playground from the screenshot above, with
attachments, a fast toggle, thinking levels, and error states:

```bash
git clone https://github.com/loginwithchatgpt/login-with-chatgpt
cd login-with-chatgpt
bun install
bun run demo   # http://localhost:3000
```

Its source is in `examples/demo/src/frontend.tsx` and is a good reference for
handling edge cases this guide skips: attachment size limits, model-list
fallbacks, and surfacing stream errors.

# Cross-origin setup (/docs/guides/cross-origin)

By default everything assumes one origin: the cookie is `SameSite=Lax`,
fetches use `credentials: "same-origin"`, and the handler rejects
cross-origin browser requests. Splitting the frontend (`app.example.com`)
from the API (`api.example.com`) takes changes on both sides.

## Server: allow the origin and loosen the cookie [#server-allow-the-origin-and-loosen-the-cookie]

```ts title="api server"
import { createChatGPTHandler } from "@opencoredev/loginwithchatgpt-server";

const auth = createChatGPTHandler({
  secret: process.env.LWC_SECRET,
  allowedOrigins: ["https://app.example.com"],
  cookie: { sameSite: "None", secure: true },
});
```

`allowedOrigins` lets the listed origins pass the CSRF check on
cookie-authenticated non-GET routes (`/login`, `/logout`, `/responses`).
Everything else still gets `403 { "error": "origin_not_allowed" }`.
`SameSite=None` lets the browser send the cookie cross-site at all, and it
requires `Secure`, so this setup is HTTPS-only.

The handler decides who may send requests. CORS response headers are still
your job: add `Access-Control-Allow-Origin` (the exact origin, never `*`),
`Access-Control-Allow-Credentials: true`, and an `OPTIONS` preflight response
in front of the handler.

## Client: include credentials everywhere [#client-include-credentials-everywhere]

The hook and the proxy provider both need the handler's absolute URL and
credentialed fetches:

```tsx title="frontend"
import { useLoginWithChatGPT } from "@opencoredev/loginwithchatgpt-react";
import { createChatGPTProxyProvider } from "@opencoredev/loginwithchatgpt-ai";

const basePath = "https://api.example.com/api/chatgpt";

const auth = useLoginWithChatGPT({
  basePath,
  fetch: (input, init) => fetch(input, { ...init, credentials: "include" }),
});

const chatgpt = createChatGPTProxyProvider({
  basePath,
  credentials: "include", // used by listModels()
  fetch: (input, init) => fetch(input, { ...init, credentials: "include" }), // used for streaming
});
```

The proxy provider has both knobs on purpose: `credentials` covers its own
`listModels()` call, and the `fetch` wrapper covers the requests the AI SDK
makes to `/responses`.

<Callout type="warn" title="Do not allow arbitrary origins">
  Every origin in `allowedOrigins` can drive the signed-in user's session
  from the browser. List your own frontends only, and never reflect the
  request origin back in CORS headers.
</Callout>

## Verify [#verify]

1. Sign in from the frontend origin and confirm the `lwc_session` cookie has
   `SameSite=None; Secure`.
2. `GET /session` from the frontend returns `authenticated`, which proves the
   cookie was sent.
3. `POST /responses` streams, and the same request from an unlisted origin
   returns `403`.

# Custom sign-in UI (/docs/guides/custom-ui)

Use the hook when the default widget's styling does not fit your app. You get
the same state machine and actions, and you own the markup. You also own the
consent step.

<Callout type="warn" title="Consent is your job now">
  The default widget forces a usage-risk consent step. With a custom UI,
  nothing forces it. Render equivalent informed consent before calling
  `login()`, or reuse `openLoginWithChatGPTConsentPopup()` below.
</Callout>

## The hook [#the-hook]

```tsx title="components/chatgpt-login.tsx"
"use client";

import { useLoginWithChatGPT } from "@opencoredev/loginwithchatgpt-react";

export function ChatGPTLogin() {
  const auth = useLoginWithChatGPT();

if (auth.status === "loading") {
    return <p>Checking ChatGPT session…</p>;
  }

if (auth.status === "authenticated") {
    return (
      <button type="button" onClick={() => void auth.logout()}>
        Disconnect {auth.user?.email}
      </button>
    );
  }

if (auth.status === "pending") {
    return (
      <section>
        <p>Enter this code in the OpenAI verification window.</p>
        <button type="button" onClick={() => void auth.copyCode()}>
          {auth.userCode}
        </button>
        {auth.copied ? <p>Copied.</p> : null}
        <button type="button" onClick={auth.reopen}>
          Reopen verification window
        </button>
      </section>
    );
  }

// unauthenticated, expired, or error: render consent, then login
  return (
    <section>
      <p>
        Continue only if you trust this app. It can send AI requests billed to
        your own ChatGPT plan.
      </p>
      <button
        type="button"
        onClick={() => void auth.login()}
        disabled={auth.isConnecting}
      >
        {auth.isConnecting ? "Connecting…" : "I trust this app, continue"}
      </button>
      {auth.error ? <p role="alert">{auth.error}</p> : null}
    </section>
  );
}
```

Every option and returned field is in the [React reference](/docs/reference/react).

## Reusing the built-in consent popup [#reusing-the-built-in-consent-popup]

`openLoginWithChatGPTConsentPopup()` opens the same consent popup the default
widget uses, then continues into `login()` inside that popup. That detail
matters: browsers only allow popups inside a direct user gesture, and this
keeps the whole flow in one window.

```tsx
import {
  openLoginWithChatGPTConsentPopup,
  useLoginWithChatGPT,
} from "@opencoredev/loginwithchatgpt-react";

const auth = useLoginWithChatGPT();

function onClick() {
  const popup = openLoginWithChatGPTConsentPopup({
    appName: "Acme",
    securityHref: "https://acme.dev/security",
    login: auth.login,
  });

if (!popup) {
    // Popup blocked. Fall back to your own inline consent, then auth.login().
  }
}
```

`login()` also accepts a pre-opened window, for when you built your own
consent popup and want the verification page to load into it:

```ts
const popup = window.open("", "login-with-chatgpt");
// render your consent into the popup, and on continue:
await auth.login({ popup });
```

## The `children` renderer [#the-children-renderer]

To restyle the widget without reimplementing polling, pass a render function.
It receives the full hook result and replaces the default UI, including the
consent step:

```tsx
<LoginWithChatGPT>
  {(auth) =>
    auth.isAuthenticated ? (
      <ConnectedChip user={auth.user} onDisconnect={auth.logout} />
    ) : (
      <MyConsentAndLogin auth={auth} />
    )
  }
</LoginWithChatGPT>
```

## Accessibility notes [#accessibility-notes]

* Use real `<button>` elements for `login`, `logout`, `copyCode`, and
  `reopen`.
* Keep the visible code selectable and offer a manual copy button. Clipboard
  writes fail silently when the page loses focus.
* Keep the verification link visible, and keep the pending state readable for
  the full 15-minute code lifetime.
* Surface `auth.error` with `role="alert"`.

# Fast tier & thinking effort (/docs/guides/fast-and-reasoning)

Two request settings are worth exposing in a chat UI: the Codex service tier
(Fast mode) and the reasoning effort, usually shown as a "thinking level".
Browser code cannot rewrite proxied bodies, so the SDK exposes both as narrow
headers. The server validates each value and writes it into the request.

## Fast tier from the browser [#fast-tier-from-the-browser]

Codex Fast mode is `service_tier: "fast"` on supported models. Send the SDK
header on any AI SDK call:

```ts
import { streamText } from "ai";

const result = streamText({
  model: chatgpt("gpt-5.5"),
  prompt: "Refactor this helper.",
  headers: {
    "x-login-with-chatgpt-service-tier": "fast",
  },
});
```

Accepted values are `auto`, `default`, `flex`, `priority`, and `fast`.
Anything else returns `400`. If upstream rejects Fast for that session or
model, the handler retries once without `service_tier`. The request still
streams, and the response carries
`x-login-with-chatgpt-service-tier-fallback: auto` so your UI can show that
Fast did not apply.

Fast is account- and model-dependent. Show the toggle only for models that
support it, and tell users it consumes their included usage faster:

```ts
const supportsFast = model === "gpt-5.5" || model === "gpt-5.4";
```

## Thinking effort from the browser [#thinking-effort-from-the-browser]

The reasoning header works the same way and lands in `reasoning.effort`:

```ts
const result = streamText({
  model: chatgpt("gpt-5.5"),
  prompt: "Review this migration plan.",
  headers: {
    "x-login-with-chatgpt-reasoning-effort": "high",
  },
});
```

Accepted values are `none`, `low`, `medium`, `high`, and `xhigh`. Invalid
values return `400`. When nothing is sent, the default is `medium`. For a
user-facing control, stick to `low` / `medium` / `high`; the outer values are
model-dependent and worth testing before you offer them.

## Defaults on the server [#defaults-on-the-server]

Both settings can also be fixed server-side instead of per request, on the
handler for proxied traffic or on the direct provider for server-side calls:

```ts title="server.ts"
const auth = createChatGPTHandler({
  secret: process.env.LWC_SECRET,
  reasoningEffort: "high",   // default for proxied requests
  serviceTier: "fast",       // applied when the body has no service_tier
});
```

```ts title="server-side provider"
const chatgpt = createChatGPT({
  credentials: tokens,
  serviceTier: "fast",
  reasoningEffort: "high",
});
```

Header values from the browser win over these defaults, because the header is
written into the body before normalization fills the gaps.

# Headless & CLI logins (/docs/guides/headless)

The browser widget is optional. For CLIs, scripts, and backend jobs, run the
device-code flow directly with `@opencoredev/loginwithchatgpt-core` and hand the tokens
to the server-side AI provider.

## A complete CLI login [#a-complete-cli-login]

```ts title="login-cli.ts"
import {
  requestDeviceCode,
  resolveConfig,
  waitForDeviceTokens,
} from "@opencoredev/loginwithchatgpt-core";
import { createChatGPT } from "@opencoredev/loginwithchatgpt-ai";
import { streamText } from "ai";

const config = resolveConfig();

const device = await requestDeviceCode(config);
console.log(`Open ${device.verificationUrl} and enter: ${device.userCode}`);

const tokens = await waitForDeviceTokens(config, device, {
  onPoll: (attempt) => console.log(`Waiting for authorization… (${attempt})`),
});

const chatgpt = createChatGPT({ credentials: tokens });
const result = streamText({
  model: chatgpt(), // defaults to gpt-5.5
  prompt: "Say hello from a CLI.",
});

for await (const delta of result.textStream) {
  process.stdout.write(delta);
}
```

The repo has a runnable version at `examples/demo/src/login-cli.ts`.

`waitForDeviceTokens()` blocks until the user authorizes, polling at the
interval OpenAI requested. It throws a `ChatGPTAuthError` with code
`authorization_expired` if the 15-minute device code runs out, and accepts an
`AbortSignal`:

```ts
const controller = new AbortController();
const tokens = await waitForDeviceTokens(config, device, {
  signal: controller.signal,
});
```

## Persisting tokens across runs [#persisting-tokens-across-runs]

`createChatGPT` accepts a credentials loader plus an `onRefresh` callback, so
rotated tokens survive process restarts:

```ts title="provider with persistence"
const chatgpt = createChatGPT({
  credentials: () => loadTokensFromDisk(),
  onRefresh: (next) => saveTokensToDisk(next),
});
```

Store the token JSON like any secret. It contains a refresh token that keeps
working until the session is revoked or expires. And reuse persisted tokens
instead of re-running the flow: each device-code authorization creates
another session against the user's account.

## Step-by-step control [#step-by-step-control]

If you want custom polling UI, drive the flow manually instead of
`waitForDeviceTokens()`:

```ts
import { exchangeDeviceAuthorization, pollDeviceCode } from "@opencoredev/loginwithchatgpt-core";

const poll = await pollDeviceCode(config, device);
if (poll.status === "authorized") {
  const tokens = await exchangeDeviceAuthorization(config, poll);
}
```

The full primitive list is in the [core reference](/docs/reference/core).

# Production checklist (/docs/guides/production)

Local defaults are forgiving on purpose: an ephemeral secret, an in-memory
store, no model restrictions. Production needs deliberate choices. Work down
this list.

## Required [#required]

Set a stable `secret` from your host's environment manager. Without one the
SDK generates an ephemeral secret per boot, and every restart logs everyone
out. Rotating the secret does the same, so plan rotations.

```bash title=".env"
LWC_SECRET="$(openssl rand -hex 32)"
```

Use a shared `sessionStore`. The default `MemoryStore` loses sessions on
restart and does not work across serverless invocations, containers, or
preview deployments. Back it with Redis or a database; the
[interface is three methods](/docs/concepts/sessions#the-session-store).

Keep consent intact. Ship the default widget's consent step, or equivalent
informed consent before `login()` in custom UIs
([why](/docs/concepts/security#user-consent)).

Use HTTPS, and confirm your reverse proxy forwards `X-Forwarded-Proto` so the
session cookie gets `Secure`
([details](/docs/concepts/sessions#the-session-cookie)).

## Proxy guardrails [#proxy-guardrails]

* Set `responsesProxy.allowedModels` to the models your product actually
  offers.
* Review the default rate limit (30 requests/minute per session) for your
  product. Pass a shared `rateLimit.store` when running multiple instances,
  because the default counter is per instance.
* Keep `responsesProxy.maxRequestBytes` (40 MiB default) in line with the
  attachments you accept, and cap prompt size and attachment types at your
  app boundary.
* Add an operator kill switch in front of `/responses` for abuse
  emergencies.
* If you need custom quotas or audit logging, wrap
  [`auth.proxyFetch(request)`](/docs/reference/server#proxyfetchrequest) in
  your own route so raw tokens still stay inside the handler.

```ts title="server.ts"
const auth = createChatGPTHandler({
  secret: process.env.LWC_SECRET,
  sessionStore: redisStore,
  responsesProxy: {
    allowedModels: ["gpt-5.5", "gpt-5.4-mini"],
    rateLimit: { limit: 20, windowMs: 60_000, store: redisRateLimitStore },
  },
});
```

## Topology [#topology]

Same-origin apps can leave `allowedOrigins` unset and keep the default
`SameSite=Lax` cookie. A split frontend and backend needs the
[cross-origin guide](cross-origin.mdx): `allowedOrigins`, `SameSite=None`,
credentialed fetches, and your own CORS headers.

Leave `dangerouslyAllowTokenExport` off for normal web apps. Only enable it
when your application server intentionally accepts custody of raw ChatGPT
bearer tokens, and never forward refresh-token export output anywhere.

## Operations [#operations]

* Give users a visible sign-out that hits `/logout`, and delete sessions
  server-side when they close their account.
* Log `/responses` metadata (session id, model, status, duration) for abuse
  review. Do not log prompts or attachments.
* Smoke-test after every deploy and dependency upgrade: login, `GET /models`
  returns slugs, one streaming response completes.
* Review OpenAI terms and policy for your use case before launch.

# AI SDK providers (/docs/reference/ai)

`@opencoredev/loginwithchatgpt-ai` adapts the ChatGPT-backed Codex responses endpoint to
the Vercel AI SDK (`ai` and `@ai-sdk/openai` are peer dependencies). Two
factories, one provider shape:

* **Proxy provider**: default for browser and app-server routes. Sends
  requests to your server handler, which injects credentials from the session
  cookie.
* **Direct provider**: headless/server-only escape hatch. Holds a user's tokens
  and calls upstream directly.

## Provider API [#provider-api]

Both factories return a `ChatGPTProvider`:

```ts
const model = chatgpt("gpt-5.5");            // a responses model
const same = chatgpt.responses("gpt-5.5");   // explicit accessor
const model2 = chatgpt();                    // uses defaultModel ("gpt-5.5")
const slugs = await chatgpt.listModels();    // string[]
const generated = await chatgpt.images.generate({ prompt, model: slugs[0] });
const edited = await chatgpt.images.edit({ prompt, images, model: slugs[0] });
const openai = chatgpt.openai;               // underlying @ai-sdk/openai provider
```

Models work with `streamText`, `generateText`, tool calling, and structured
output, plus anything else the AI SDK responses model supports. The provider's
`images` client generates and edits images through the signed-in user's
ChatGPT plan. Embeddings and audio are not provided.

## Images [#images]

Both proxy and direct providers expose the same `chatgpt.images` client. It
uses the existing `/responses` route, so it does not expose tokens or require
an API key.

Always discover a mainline model from the signed-in account first:

```ts
const models = await chatgpt.listModels();
const model = models[0];
if (!model) throw new Error("No ChatGPT models were returned for this account.");
```

### Generate [#generate]

```ts
const result = await chatgpt.images.generate({
  model,
  prompt: "An editorial photograph of a cobalt chair in a sunlit concrete room",
  size: "2048x2048",
  quality: "high",
  format: "webp",
  compression: 80,
  background: "opaque",
  n: 2,
  partialImages: 2,
  onPartialImage(partial) {
    preview.src = partial.dataUrl;
  },
});

const first = result.data[0];
first.base64;   // raw base64 bytes
first.dataUrl;  // data:image/webp;base64,...
first.mediaType;
```

### Edit [#edit]

Editing is stateless: the client sends every source image with the edit
request. It accepts remote URLs, data URLs, raw base64, `Blob`, `ArrayBuffer`,
and `Uint8Array` inputs.

```ts
const result = await chatgpt.images.edit({
  model,
  prompt: "Replace only the background with a warm plaster wall.",
  images: [{ data: sourceBlob, detail: "high" }],
  mask: { data: maskBytes, mediaType: "image/png" },
  inputFidelity: "high",
  size: "1536x1024",
  quality: "high",
  format: "png",
});

image.src = result.data[0].dataUrl;
```

### Image options [#image-options]

| Option           | Type                            | Notes                                                             |
| ---------------- | ------------------------------- | ----------------------------------------------------------------- |
| `prompt`         | `string`                        | Required generation or editing instruction.                       |
| `model`          | `string`                        | Mainline model returned by `listModels()`.                        |
| `imageModel`     | `string`                        | Optional GPT Image model override; otherwise the tool selects it. |
| `size`           | `"auto"` or dimensions          | Popular sizes include `1024x1024`, `2048x2048`, and `3840x2160`.  |
| `quality`        | `auto \| low \| medium \| high` | Rendering quality.                                                |
| `format`         | `png \| jpeg \| webp`           | Default `png`.                                                    |
| `compression`    | `0..100`                        | JPEG/WebP output compression.                                     |
| `background`     | `auto \| opaque \| transparent` | Support depends on the selected image model.                      |
| `n`              | `1..10`                         | Runs independent image requests and returns all results in order. |
| `partialImages`  | `0..3`                          | Requests intermediate previews for each result.                   |
| `onPartialImage` | callback                        | Receives base64, data URL, result index, and partial index.       |
| `signal`         | `AbortSignal`                   | Cancels the request.                                              |
| `images`         | `ChatGPTImageInput[]`           | Required by `edit()`; multiple reference images are supported.    |
| `mask`           | `ChatGPTImageInput`             | Optional edit mask.                                               |
| `inputFidelity`  | `low \| high`                   | Detail preservation for edits.                                    |

Raw base64 and byte inputs require an `image/*` `mediaType`. A `Blob` can use
its own image MIME type. `ChatGPTImageError` exposes `status`, `code`, and
`detail` when the upstream request fails.

## `createChatGPTProxyProvider(options?)` [#createchatgptproxyprovideroptions]

```ts title="browser"
import { createChatGPTProxyProvider } from "@opencoredev/loginwithchatgpt-ai";
import { streamText } from "ai";

const chatgpt = createChatGPTProxyProvider();

const result = streamText({
  model: chatgpt("gpt-5.5"),
  prompt: "Explain cache invalidation in two sentences.",
});
```

| Option         | Type                     | Default          | Notes                                                                           |
| -------------- | ------------------------ | ---------------- | ------------------------------------------------------------------------------- |
| `basePath`     | `string`                 | `"/api/chatgpt"` | Handler mount path. Use an absolute URL for cross-origin setups.                |
| `fetch`        | `FetchLike`              | global `fetch`   | Wraps the AI SDK's own requests to `/responses`.                                |
| `credentials`  | `RequestCredentials`     | `"same-origin"`  | Used by `listModels()` and `images.*()` requests; use `"include"` cross-origin. |
| `headers`      | `Record<string, string>` | n/a              | Extra headers on every request.                                                 |
| `defaultModel` | `string`                 | `"gpt-5.5"`      | Used by `chatgpt()` with no argument.                                           |

`listModels()` throws a `ChatGPTProxyError` (with a `status` field) on non-OK
responses. Check `status === 401` to detect a signed-out user. Cross-origin
setups need both `credentials` and a `fetch` wrapper; see the
[cross-origin guide](../guides/cross-origin.mdx).

The same provider is also the recommended app-server route pattern. Bind it to
the current request with `auth.proxyFetch(request)`:

```ts title="app/api/chat/route.ts"
import { createChatGPTProxyProvider } from "@opencoredev/loginwithchatgpt-ai";
import { streamText } from "ai";

export async function POST(request: Request) {
  const chatgpt = createChatGPTProxyProvider({
    fetch: auth.proxyFetch(request),
  });
  const { prompt } = await request.json();
  const result = streamText({ model: chatgpt(), prompt });
  return result.toUIMessageStreamResponse();
}
```

## `createChatGPT(options)` [#createchatgptoptions]

Use this only when you intentionally manage token custody yourself, such as a
CLI/headless app or a migration path. Normal web apps should use
`createChatGPTProxyProvider()` with `/responses` or `auth.proxyFetch(request)`.

```ts title="headless-server"
import { createChatGPT } from "@opencoredev/loginwithchatgpt-ai";
import { streamText } from "ai";

const chatgpt = createChatGPT({ credentials: tokens });
const result = streamText({ model: chatgpt(), prompt });
```

| Option                    | Type                                                             | Default     | Notes                                                                                                                                            |
| ------------------------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `credentials`             | `ChatGPTTokens \| () => ChatGPTTokens \| Promise<ChatGPTTokens>` | required    | Static tokens or a loader.                                                                                                                       |
| `onRefresh`               | `(tokens: ChatGPTTokens) => void \| Promise<void>`               | n/a         | Persist rotated tokens when you manage them yourself.                                                                                            |
| `headers`                 | `Record<string, string>`                                         | n/a         | Extra headers on upstream requests.                                                                                                              |
| `defaultModel`            | `string`                                                         | `"gpt-5.5"` | Used by `chatgpt()` with no argument.                                                                                                            |
| + `CodexResponsesOptions` | n/a                                                              | n/a         | `instructions`, `reasoningEffort`, `reasoningSummary`, `textVerbosity`, `serviceTier`; see [server defaults](server.mdx#codex-request-defaults). |
| + `ChatGPTConfig`         | n/a                                                              | n/a         | Upstream overrides; see [core reference](core.mdx#chatgptconfig).                                                                                |

### Refresh behavior [#refresh-behavior]

* Tokens with a `refreshToken` refresh in place. Pass `onRefresh` to persist
  rotations (see [Headless & CLI logins](../guides/headless.mdx)).
* Tokens without a `refreshToken` cannot self-refresh. If `credentials` is a
  function, the provider calls it again when the access token expires, so pass a
  loader for long-lived direct providers.
* Tokens without an `accountId` throw `ChatGPTAuthError` with code
  `invalid_token`.

## What the transport does [#what-the-transport-does]

Both providers route through `createCodexFetch()` from core, which adds auth
headers and the `client_version` query parameter, then rewrites the body for
the stateless Codex backend. The full rule list is in
[Response proxy](../concepts/response-proxy.mdx#request-normalization).

## Attachments [#attachments]

Send files through the standard AI SDK `messages` shape; the transport passes
them through untouched:

```ts
const result = streamText({
  model: chatgpt(model),
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Summarize this file." },
        { type: "file", data: dataUrl, mediaType: "application/pdf", filename: "report.pdf" },
      ],
    },
  ],
});
```

The proxy's `maxRequestBytes` (40 MiB default) counts the full JSON body,
including base64 file data.

# Core primitives (/docs/reference/core)

`@opencoredev/loginwithchatgpt-core` contains the primitives the other packages are built
on. Reach for it when building [headless logins](/docs/guides/headless), custom
handlers, or tests. Typical apps never import it directly.

It has no dependencies and runs anywhere with Web-standard `fetch` and
`crypto`.

## `ChatGPTConfig` [#chatgptconfig]

Every package accepts these fields and resolves them with `resolveConfig()`:

| Option          | Default                                   | Notes                                                                                             |
| --------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `clientId`      | the public Codex client id                | Override only if you control a compatible client.                                                 |
| `issuer`        | `"https://auth.openai.com"`               | Derives the OAuth, device-code, and token URLs.                                                   |
| `scope`         | `"openid profile email offline_access"`   | `offline_access` is required for refresh tokens.                                                  |
| `codexBaseUrl`  | `"https://chatgpt.com/backend-api/codex"` | Base URL for models and responses.                                                                |
| `originator`    | `"codex_cli_rs"`                          | Sent as a header to upstream endpoints.                                                           |
| `clientVersion` | `"0.142.5"`                               | Gates model availability; see [client version drift](/docs/concepts/models#client-version-drift). |
| `fetch`         | global `fetch`                            | Inject for testing, proxying, or exotic runtimes.                                                 |

The concrete defaults are exported as constants (`DEFAULT_CLIENT_ID`,
`DEFAULT_ISSUER`, `DEFAULT_SCOPE`, `DEFAULT_CODEX_BASE_URL`,
`DEFAULT_ORIGINATOR`, `DEFAULT_CLIENT_VERSION`, `DEFAULT_MODEL`). Treat them
as operational defaults, not guarantees. The upstream endpoints can change
independently of this package.

## Device flow [#device-flow]

```ts
import {
  requestDeviceCode,
  pollDeviceCode,
  exchangeDeviceAuthorization,
  waitForDeviceTokens,
  resolveConfig,
} from "@opencoredev/loginwithchatgpt-core";

const config = resolveConfig();
const device = await requestDeviceCode(config);
// { deviceAuthId, userCode, verificationUrl, interval, expiresAt }
```

* `pollDeviceCode(config, device)` runs one poll and returns
  `{ status: "pending" }` or `{ status: "authorized", … }`.
* `exchangeDeviceAuthorization(config, poll)` trades an authorized poll
  result for `ChatGPTTokens`.
* `waitForDeviceTokens(config, device, options?)` is the loop in one call, with
  `signal`, `onPoll`, and `intervalMs` options.

Device codes live for 15 minutes (`DEVICE_CODE_TTL_MS`).

## Tokens [#tokens]

```ts
interface ChatGPTTokens {
  accessToken: string;
  refreshToken?: string;
  idToken?: string;
  accountId?: string; // chatgpt_account_id claim
  expiresAt?: number; // epoch ms
}
```

* `refreshTokens(config, refreshToken)` performs one refresh and throws
  `refresh_token_invalid` when the token is dead.
* `ensureFreshTokens(config, tokens, { onRefresh?, force? })` refreshes only
  when needed (60-second early margin), with a persistence callback.
* `isAccessTokenExpired(tokens)` is the same margin check, standalone.
* `isRefreshTokenInvalid(error)` is the type guard for the dead-refresh-token case.

## JWT and PKCE helpers [#jwt-and-pkce-helpers]

* `parseUser(idToken)` builds `ChatGPTUser` (`accountId`, `email`, `name`,
  `plan`) from id-token claims.
* `decodeJwt(token)`, `getTokenExpiry(token)`, and `deriveAccountId(token)`
  decode payloads without verifying signatures, so treat their output as
  claims, not proof.
* `generatePkce()`, `createState()`, and `randomToken(length?)` support the
  loopback redirect flow (`createAuthorizationUrl()` plus
  `exchangeAuthorizationCode()`), which exists alongside the device flow for
  environments that can listen on localhost.

## Codex transport [#codex-transport]

This layer makes AI SDK traffic acceptable to the ChatGPT-backed backend:

* `createCodexFetch({ config, getAuth, ...CodexResponsesOptions })` returns a
  fetch-compatible function that rewrites URLs onto `codexBaseUrl`, injects
  the bearer token and `chatgpt-account-id` header, adds `client_version`,
  and normalizes `/responses` bodies.
* `normalizeResponsesBody(body, options?)` is the body rewrite by itself
  ([rules](/docs/concepts/response-proxy#request-normalization)).
* `listCodexModels({ config, getAuth })` and `extractCodexModelSlugs(value)`
  handle model listing and tolerant slug extraction.

## Store [#store]

`KeyValueStore<T>` and `MemoryStore<T>` are the
[session-store contract](/docs/concepts/sessions#the-session-store) used by
the server package, exported here so custom stores need no extra dependency.

Everything these functions can throw is listed in
[Error codes](errors.mdx).

# Error codes (/docs/reference/errors)

The SDK throws one error class from core and server code, and one from the
browser proxy provider. HTTP routes return structured JSON errors.

## `ChatGPTAuthError` [#chatgptautherror]

```ts
import { ChatGPTAuthError, isRefreshTokenInvalid } from "@opencoredev/loginwithchatgpt-core";

try {
  await auth.getModels(request);
} catch (error) {
  if (error instanceof ChatGPTAuthError) {
    error.code;   // machine-readable code below
    error.status; // upstream HTTP status, when there was one
    error.body;   // upstream body snippet, when there was one
  }
}
```

| Code                            | Thrown when                                                                                                                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `device_code_request_failed`    | Upstream refused to issue a device code.                                                                                                                                             |
| `device_code_disabled`          | The device-code endpoint returned 404, so the flow is unavailable for this issuer/client.                                                                                            |
| `authorization_pending`         | Polling continued past what the caller allowed.                                                                                                                                      |
| `authorization_expired`         | The 15-minute device code ran out, or `waitForDeviceTokens()` was aborted.                                                                                                           |
| `token_exchange_failed`         | Exchanging the authorization code for tokens failed.                                                                                                                                 |
| `token_refresh_failed`          | A refresh failed for a reason other than a dead token (network blip, 5xx). Usually retryable.                                                                                        |
| `refresh_token_invalid`         | OpenAI reported the refresh token as expired, reused, or invalidated. The session is dead. The handler deletes it and reports `expired`. Detect with `isRefreshTokenInvalid(error)`. |
| `not_authenticated`             | An operation needed tokens and none exist.                                                                                                                                           |
| `invalid_token`                 | Tokens lack a usable `accountId`.                                                                                                                                                    |
| `token_export_disabled`         | Raw token export was requested without `dangerouslyAllowTokenExport`.                                                                                                                |
| `refresh_token_export_disabled` | Refresh-token export was requested without `dangerouslyAllowRefreshTokenExport`.                                                                                                     |
| `network_error`                 | The upstream request itself failed (DNS, timeout, offline).                                                                                                                          |
| `models_request_failed`         | `GET /models` upstream call failed.                                                                                                                                                  |
| `responses_request_failed`      | The proxied `/responses` upstream call failed.                                                                                                                                       |

## HTTP error shapes [#http-error-shapes]

Returned by the [handler routes](routes.mdx):

| Status                   | Body                                                                                                                           | Route(s)                    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
| `400`                    | `{ "error": "invalid_responses_request", "message": "…" }`                                                                     | `/responses`                |
| `400`                    | `{ "error": "invalid_service_tier", "serviceTier": "…" }` or `{ "error": "invalid_reasoning_effort", "reasoningEffort": "…" }` | `/responses`                |
| `401`                    | `{ "error": "not_authenticated" }`                                                                                             | `/models`, `/responses`     |
| `403`                    | `{ "error": "model_not_allowed", "model": "…" }`                                                                               | `/responses`                |
| `403`                    | `{ "error": "origin_not_allowed", "origin": "…" }`                                                                             | all non-GET routes          |
| `404` / `405`            | plain text, `405` includes an `Allow` header                                                                                   | unknown path / wrong method |
| `413`                    | `{ "error": "responses_request_too_large", "maxRequestBytes": … }`                                                             | `/responses`                |
| `429`                    | `{ "error": "rate_limited", "retryAfterSeconds": … }` with a `retry-after` header                                              | `/responses`                |
| upstream status          | `{ "error": "responses_request_failed", "status": …, "detail": "…" }`                                                          | `/responses`                |
| upstream status or `502` | `{ "models": [], "error": "<code>", "message": "…" }`                                                                          | `/models`                   |

## `ChatGPTProxyError` [#chatgptproxyerror]

Thrown by the browser proxy provider's `listModels()` when your handler
answers non-OK:

```ts
import { ChatGPTProxyError } from "@opencoredev/loginwithchatgpt-ai";

try {
  await chatgpt.listModels();
} catch (error) {
  if (error instanceof ChatGPTProxyError && error.status === 401) {
    // signed out; show the login button
  }
}
```

Streaming errors from `/responses` surface through the AI SDK's own error
types instead (see
[Troubleshooting](troubleshooting.mdx#ai-sdk-throws-ai_nooutputgeneratederror)).

[Troubleshooting](troubleshooting.mdx) covers the same failures organized by
symptom instead of by code.

# React (/docs/reference/react)

`@opencoredev/loginwithchatgpt-react` ships two layers over the same state machine: a
drop-in widget and a hook for custom UIs. Both are client components and
require a mounted [server handler](server.mdx).

## `<LoginWithChatGPT />` [#loginwithchatgpt-]

```tsx title="components/sign-in.tsx"
"use client";

import { LoginWithChatGPT } from "@opencoredev/loginwithchatgpt-react";

export function SignIn() {
  return (
    <LoginWithChatGPT
      consent={{ appName: "Acme", securityHref: "https://acme.dev/security" }}
      onAuthenticated={(user) => console.log("connected", user?.email)}
      onError={(error) => console.error(error)}
    />
  );
}
```

### Props [#props]

Accepts every [hook option](#options) plus:

| Prop                 | Type                                             | Default                | Notes                                                                                                                 |
| -------------------- | ------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `label`              | `string`                                         | `"Login with ChatGPT"` | Initial button label.                                                                                                 |
| `consent`            | `{ appName?, continueLabel?, securityHref? }`    | `{}`                   | Customizes the consent copy. The consent step itself always renders and cannot be turned off.                         |
| `className`, `style` | —                                                | —                      | Applied to the root element.                                                                                          |
| `children`           | `(auth: UseLoginWithChatGPTResult) => ReactNode` | —                      | Full custom renderer. Replaces all default UI, including consent. Render equivalent consent before calling `login()`. |

### What it renders [#what-it-renders]

| State               | UI                                                                                                          |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `loading`           | Spinner with "Checking session…".                                                                           |
| `unauthenticated`   | The login button. Clicking opens the consent popup; if popups are blocked, the same consent renders inline. |
| `connecting`        | Disabled button with spinner.                                                                               |
| `pending`           | The user code with a copy button, verification link, and hint.                                              |
| `authenticated`     | Connected chip with avatar, plan, and a Disconnect button.                                                  |
| `expired` / `error` | Retryable error state; `error` text renders below the UI.                                                   |

The widget injects one `<style id="lwc-styles">` element with `.lwc-*` classes
on first mount. Override those classes to restyle without a custom renderer.

## `useLoginWithChatGPT()` [#useloginwithchatgpt]

```tsx
"use client";

import { useLoginWithChatGPT } from "@opencoredev/loginwithchatgpt-react";

const auth = useLoginWithChatGPT({ pollIntervalMs: 2500 });
```

See [Custom sign-in UI](/docs/guides/custom-ui) for a complete example.

### Options [#options]

| Option            | Type                           | Default          | Notes                                                                                                                     |
| ----------------- | ------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `basePath`        | `string`                       | `"/api/chatgpt"` | Must match the handler's `basePath`.                                                                                      |
| `fetch`           | `typeof fetch`                 | global `fetch`   | For credentialed or cross-origin requests.                                                                                |
| `pollIntervalMs`  | `number`                       | `2500`           | Client cadence while `pending`. The server still respects the upstream interval, so lower values only tighten UI latency. |
| `openPopup`       | `boolean`                      | `true`           | Open the verification URL after starting login.                                                                           |
| `autoCopyCode`    | `boolean`                      | `true`           | Copy the user code before opening the popup (clipboard writes fail after focus loss).                                     |
| `onAuthenticated` | `(user?: ChatGPTUser) => void` | —                | Fires when status becomes `authenticated`.                                                                                |
| `onError`         | `(error: Error) => void`       | —                | Fires when login startup fails.                                                                                           |

### Returned value [#returned-value]

```ts
interface UseLoginWithChatGPTResult {
  status: "loading" | "unauthenticated" | "connecting" | "pending"
        | "authenticated" | "expired" | "error";
  user?: ChatGPTUser;          // when authenticated
  userCode?: string;           // when pending
  verificationUrl?: string;    // when pending
  copied: boolean;             // true briefly after a clipboard write
  error?: string;

login(options?: { popup?: Window | null }): Promise<void>;
  logout(): Promise<void>;
  copyCode(): Promise<void>;
  reopen(): void;              // refocus or reopen the verification popup

isAuthenticated: boolean;
  isPending: boolean;
  isConnecting: boolean;
}
```

Behavior notes:

* On mount the hook checks `GET /session` once. Until it answers, `status`
  is `"loading"`.
* `login({ popup })` navigates a pre-opened window instead of opening a new
  one. That is how the consent popup hands itself over.
* `logout()` clears local state even if the network call fails.
* All requests use `credentials: "same-origin"` unless you pass a `fetch`
  wrapper.

## `openLoginWithChatGPTConsentPopup()` [#openloginwithchatgptconsentpopup]

Opens the built-in consent popup and, on continue, calls your `login` with
that popup so the verification page loads in the same window:

```ts
import { openLoginWithChatGPTConsentPopup } from "@opencoredev/loginwithchatgpt-react";

const popup = openLoginWithChatGPTConsentPopup({
  appName: "Acme",
  continueLabel: "I trust this app, continue",
  securityHref: "https://acme.dev/security",
  login: auth.login,
});
// null when the popup was blocked — fall back to inline consent.
```

## Icons [#icons]

`ChatGPTMark` and `Spinner` are exported as plain SVG components
(`fill="currentColor"`, `aria-hidden`). `OpenAIMark` is a deprecated alias of
`ChatGPTMark` kept for older imports.

For a full custom-UI walkthrough with consent patterns, see
[Custom sign-in UI](/docs/guides/custom-ui).

# HTTP routes (/docs/reference/routes)

All paths are relative to `basePath` (default `/api/chatgpt`). Responses are
JSON unless noted. Unknown paths return a plain-text `404`; a known path with
the wrong method returns `405` with an `Allow` header.

## `POST /login` [#post-login]

Starts a device login, or reuses the session's still-valid pending device code
without calling upstream again. Sets the session cookie when none exists.

```json title="200"
{
  "status": "pending",
  "userCode": "7B0J-DPK78",
  "verificationUrl": "https://auth.openai.com/codex/device",
  "interval": 5,
  "expiresAt": 1780000000000
}
```

## `GET /status` [#get-status]

Advances the login by at most one upstream poll (respecting `interval`), then
returns public state. While pending it returns the device fields above; token
refresh also happens here for authenticated sessions near expiry.

```json title="200"
{
  "status": "authenticated",
  "user": { "accountId": "acct_…", "email": "user@example.com", "plan": "pro" }
}
```

`status` is one of `unauthenticated`, `pending`, `authenticated`, `expired`,
`error`.

## `GET /session` [#get-session]

Same response shape as `/status`, but never polls upstream, so it is a cheap read for
initial page loads.

## `POST /logout` [#post-logout]

Deletes the session from the store and clears the cookie (`Max-Age=0`).

```json title="200"
{ "status": "unauthenticated" }
```

## `GET /models` [#get-models]

Requires an authenticated session; refreshes tokens, then lists the account's
model slugs. Disabled when `enableResponsesProxy: false`.

```json title="200"
{ "models": ["gpt-5.5", "gpt-5.4", "gpt-5.4-mini"] }
```

| Status                   | Body                                                  |
| ------------------------ | ----------------------------------------------------- |
| `401`                    | `{ "error": "not_authenticated" }`                    |
| upstream status or `502` | `{ "models": [], "error": "<code>", "message": "…" }` |

## `POST /responses` [#post-responses]

The streaming proxy. Accepts a Responses-API JSON body, injects credentials,
normalizes it for the Codex backend, and streams the upstream body back with
`cache-control: no-store`. Disabled when `enableResponsesProxy: false`.

Request headers the proxy understands
(details in [Fast tier & thinking effort](/docs/guides/fast-and-reasoning)):

| Header                                  | Accepted values                               |
| --------------------------------------- | --------------------------------------------- |
| `x-login-with-chatgpt-service-tier`     | `auto`, `default`, `flex`, `priority`, `fast` |
| `x-login-with-chatgpt-reasoning-effort` | `none`, `low`, `medium`, `high`, `xhigh`      |

| Status          | Body / behavior                                                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `200`           | Upstream stream, content type forwarded from upstream.                                                                             |
| `400`           | `{ "error": "invalid_responses_request", "message": "…" }`, `invalid_service_tier`, or `invalid_reasoning_effort`.                 |
| `401`           | `{ "error": "not_authenticated" }` when there is no live session.                                                                  |
| `403`           | `{ "error": "model_not_allowed", "model": "…" }` or `{ "error": "origin_not_allowed", … }`.                                        |
| `413`           | `{ "error": "responses_request_too_large", "maxRequestBytes": … }`.                                                                |
| `429`           | `{ "error": "rate_limited", "retryAfterSeconds": … }` plus a `retry-after` header.                                                 |
| upstream status | `{ "error": "responses_request_failed", "status": …, "detail": "…" }`. The handler also logs the upstream status and body snippet. |

When a `fast` service tier is rejected upstream, the handler retries once
without it and adds `x-login-with-chatgpt-service-tier-fallback: auto` to the
response.

## CSRF rules [#csrf-rules]

All non-GET routes (`/login`, `/logout`, `/responses`) check the `Origin`
header on browser requests:

* Same-origin requests and origins listed in `allowedOrigins` pass.
* Other origins get `403 { "error": "origin_not_allowed" }`.
* Requests without an `Origin` header (curl, server-to-server) always pass;
  they cannot carry a browser's ambient cookie.

## Cookie [#cookie]

One cookie, `lwc_session` by default: an HMAC-signed random id, `HttpOnly`,
`SameSite=Lax`, `Path=/`, `Max-Age` from `sessionTtlMs`, and `Secure` when the
request is HTTPS (directly or via `X-Forwarded-Proto`). Attributes are
configurable via the [`cookie` option](server.mdx#server-options).

All error shapes, including the ones thrown as exceptions rather than
returned as JSON, are collected in [Error codes](errors.mdx).

# Server handler (/docs/reference/server)

```ts
import { createChatGPTHandler } from "@opencoredev/loginwithchatgpt-server";

const auth = createChatGPTHandler(options);
```

Returns a `ChatGPTHandler`:

```ts
interface ChatGPTHandler {
  basePath: string;
  handler: (request: Request) => Promise<Response>;
  fetch: (request: Request) => Promise<Response>; // alias of handler
  proxyFetch: (request: Request) => typeof fetch;
  getSession: (request: Request) => Promise<PublicSession>;
  getModels: (request: Request) => Promise<string[] | undefined>;
  dangerouslyGetTokens: (request: Request, options?: { includeRefreshToken?: boolean }) => Promise<ChatGPTTokens | undefined>;
  /** @deprecated Prefer proxyFetch(), /responses, or /models. */
  getTokens: (request: Request, options?: { includeRefreshToken?: boolean }) => Promise<ChatGPTTokens | undefined>;
}
```

Mount `handler` at `${basePath}/*`. It only requires Web-standard `Request`,
`Response`, `fetch`, and `crypto.subtle`, so use it in runtimes that provide
those APIs. The routes it serves are documented in [HTTP routes](routes.mdx).

## Options [#options]

### Server options [#server-options]

| Option                               | Type                           | Default                   | Notes                                                                                                                                           |
| ------------------------------------ | ------------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `basePath`                           | `string`                       | `"/api/chatgpt"`          | Mount path; leading `/` added, trailing `/` stripped.                                                                                           |
| `secret`                             | `string`                       | ephemeral random          | Signs cookies (HMAC-SHA256) and encrypts tokens (AES-GCM). Logs a warning when omitted. Always set it outside local dev.                        |
| `sessionStore`                       | `KeyValueStore<StoredSession>` | `new MemoryStore()`       | Use a shared store in production.                                                                                                               |
| `cookieName`                         | `string`                       | `"lwc_session"`           | Session cookie name.                                                                                                                            |
| `cookie`                             | `Partial<CookieOptions>`       | `{}`                      | Overrides: `path`, `domain`, `maxAge`, `secure`, `httpOnly`, `sameSite`.                                                                        |
| `sessionTtlMs`                       | `number`                       | `2_592_000_000` (30 days) | Session and cookie lifetime.                                                                                                                    |
| `defaultModel`                       | `string`                       | `"gpt-5.5"`               | Injected when a `/responses` body omits `model`.                                                                                                |
| `enableResponsesProxy`               | `boolean`                      | `true`                    | `false` disables the `/responses` **and** `/models` routes.                                                                                     |
| `responsesProxy`                     | `ResponsesProxyPolicy`         | `{}`                      | Guardrails below.                                                                                                                               |
| `allowedOrigins`                     | `readonly string[]`            | `[]`                      | Extra origins allowed on cookie-authenticated non-GET routes.                                                                                   |
| `dangerouslyAllowTokenExport`        | `boolean`                      | `false`                   | Enables `dangerouslyGetTokens()` / deprecated `getTokens()`. Only use when your server code intentionally accepts custody of raw bearer tokens. |
| `dangerouslyAllowRefreshTokenExport` | `boolean`                      | `false`                   | Also allows `{ includeRefreshToken: true }`. Requires `dangerouslyAllowTokenExport`; use only for deliberate migration/export flows.            |

### `responsesProxy` [#responsesproxy]

| Option            | Type                                              | Default                           | Notes                                                                                                              |
| ----------------- | ------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `allowedModels`   | `readonly string[] \| (model: string) => boolean` | all allowed                       | Disallowed models get `403 model_not_allowed`.                                                                     |
| `maxRequestBytes` | `number`                                          | `41_943_040` (40 MiB)             | Maximum raw JSON body size, including base64 image-editing inputs.                                                 |
| `rateLimit`       | `false \| { limit?, windowMs?, store? }`          | `{ limit: 30, windowMs: 60_000 }` | Per-session limit; `false` disables. Default store is per-instance memory; pass a shared `store` across instances. |

### Codex request defaults [#codex-request-defaults]

Applied to proxied `/responses` bodies when the request does not set them
(see [request normalization](../concepts/response-proxy.mdx#request-normalization)):

| Option             | Type                                                    | Effective default          | Notes                                                                               |
| ------------------ | ------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------- |
| `instructions`     | `string`                                                | a generic assistant prompt | Sent when the body has no `instructions`.                                           |
| `reasoningEffort`  | `"none" \| "low" \| "medium" \| "high" \| "xhigh"`      | `"medium"`                 | Overridden per request by the [reasoning header](../guides/fast-and-reasoning.mdx). |
| `reasoningSummary` | `string`                                                | `"auto"`                   | Merged into `reasoning`.                                                            |
| `textVerbosity`    | `"low" \| "medium" \| "high"`                           | `"medium"`                 | Merged into `text`.                                                                 |
| `serviceTier`      | `"auto" \| "default" \| "flex" \| "priority" \| "fast"` | unset                      | Applied when the body has no `service_tier`.                                        |

### Upstream configuration [#upstream-configuration]

Inherited from `ChatGPTConfig`. Override only when you know why
([core reference](core.mdx#chatgptconfig)): `clientId`, `issuer`, `scope`,
`codexBaseUrl`, `originator`, `clientVersion`, `fetch`.

## Helpers [#helpers]

All three read the session cookie from the request and are safe in any server
context (route handlers, server components, middleware).

### `getSession(request)` [#getsessionrequest]

Returns public state without touching upstream:

```ts
const session = await auth.getSession(request);
// { status: "authenticated", user: { accountId, email, name, plan } }
// or { status: "unauthenticated" | "pending" | "expired" | "error" }
```

### `proxyFetch(request)` [#proxyfetchrequest]

Creates a request-scoped fetch that carries the user's session cookie back
through the mounted handler. Use it when you want a custom server route with
AI SDK control, but you do not want application code to receive bearer tokens:

```ts title="app/api/chat/route.ts"
import { createChatGPTProxyProvider } from "@opencoredev/loginwithchatgpt-ai";
import { streamText } from "ai";

export async function POST(request: Request) {
  const chatgpt = createChatGPTProxyProvider({
    fetch: auth.proxyFetch(request),
  });
  const { prompt } = await request.json();

const result = streamText({ model: chatgpt(), prompt });
  return result.toUIMessageStreamResponse();
}
```

The provider still calls `/api/chatgpt/responses` and `/api/chatgpt/models`;
the handler loads, refreshes, and injects credentials internally.

### `getModels(request)` [#getmodelsrequest]

Returns the account's model slugs, or `undefined` when unauthenticated.
Refreshes tokens before calling upstream. Throws `ChatGPTAuthError` with code
`models_request_failed` on upstream failure.

### `dangerouslyGetTokens(request, options?)` [#dangerouslygettokensrequest-options]

Disabled unless `createChatGPTHandler({ dangerouslyAllowTokenExport: true })`
is set. When enabled, returns a fresh access token plus account id, with the
refresh token redacted by default.

Exporting bearer tokens moves trust from the SDK boundary into your application
code: server code can log, copy, or forward them. Prefer `proxyFetch(request)`
for request handling. Only enable this for advanced integrations that
intentionally accept that custody model.

```ts
const tokens = await auth.dangerouslyGetTokens(request);
// { accessToken, accountId, expiresAt } with no refreshToken

const exported = await auth.dangerouslyGetTokens(request, {
  includeRefreshToken: true,
});
// Requires dangerouslyAllowRefreshTokenExport: true. Use only for migration/export flows.
```

## Session storage [#session-storage]

Sessions are stored under the cookie's session id. When `secret` is set, token
JSON is AES-GCM encrypted before writing. The store contract:

```ts
interface KeyValueStore<T> {
  get(key: string): Promise<T | undefined> | T | undefined;
  set(key: string, value: T, options?: { ttlMs?: number }): Promise<void> | void;
  delete(key: string): Promise<void> | void;
}
```

`MemoryStore` (exported for tests and local dev) enforces TTL lazily at read
time. How the cookie, store, and refresh cycle fit together is covered in
[Sessions & tokens](../concepts/sessions.mdx).

# Troubleshooting (/docs/reference/troubleshooting)

Start by probing the routes in order. Each one only works if the previous
layer is healthy:

```bash
curl -i -X POST http://localhost:3000/api/chatgpt/login     # handler mounted?
curl -i http://localhost:3000/api/chatgpt/session           # cookie & store?
curl -i http://localhost:3000/api/chatgpt/models            # tokens & upstream?
```

Authenticated routes need the session cookie — probe them from the browser
devtools console, or copy the cookie from a successful login.

## The popup did not open [#the-popup-did-not-open]

Browsers only allow popups inside a direct user gesture.

* Call `login()` (or open the consent popup) synchronously from the click
  handler — do not `await` other work first.
* Check `openPopup` is still `true`.
* Expose `reopen()` as a button so users can recover from a blocked popup. The
  default widget falls back to inline consent automatically.

## The code did not copy [#the-code-did-not-copy]

Clipboard writes fail silently when the page loses focus or permission is
denied — the SDK treats copying as best-effort. Always render the code
visibly with a manual copy button.

## `/session` stays `unauthenticated` [#session-stays-unauthenticated]

In likely order:

1. The browser is not sending the `lwc_session` cookie (wrong origin, or
   missing `credentials: "include"` cross-origin).
2. `basePath` on the client does not match the handler.
3. The session store is process-local and this request hit another instance.
   Use a [shared store](/docs/concepts/sessions#the-session-store).
4. The user never finished the OpenAI authorization, or the code expired.

Confirm server-side before debugging React:

```ts
const session = await auth.getSession(request);
```

## `/models` returns 401 [#models-returns-401]

No authenticated session on that request. Send the user through login, or
check the cookie is included (`credentials: "same-origin"` locally,
`"include"` plus [cross-origin setup](/docs/guides/cross-origin) for split
deployments).

## Models are empty or "not supported" [#models-are-empty-or-not-supported]

The account, plan, or `clientVersion` does not expose the model you picked.

1. Call `listModels()` and pick only from that list.
2. If the list itself is empty or the request fails, bump `clientVersion` —
   see [client version drift](/docs/concepts/models#client-version-drift).

## AI SDK throws `AI_NoOutputGeneratedError` [#ai-sdk-throws-ai_nooutputgeneratederror]

The upstream stream contained no assistant text. Check the server log first.
The handler logs upstream `/responses` failures as
`[login-with-chatgpt] Codex /responses <status>: <body>`. Then verify:

* the `model` came from `listModels()`,
* the body does not rely on fields the
  [normalizer strips](/docs/concepts/response-proxy#request-normalization),
* `clientVersion` is current for the account.

## Requests return 429 [#requests-return-429]

The per-session rate limit (30/minute by default) fired. Honor the
`retry-after` header, and review
[`responsesProxy.rateLimit`](/docs/reference/server#responsesproxy) if the
default does not fit your product.

## Sessions disappear after restart [#sessions-disappear-after-restart]

You are using the in-memory store, an ephemeral secret, or both. Set a stable
`LWC_SECRET` and a shared `sessionStore` — see the
[production checklist](/docs/guides/production#required).

## Session suddenly reports `expired` [#session-suddenly-reports-expired]

OpenAI invalidated the refresh token (revoked, reused, or expired). The
handler deletes the dead session automatically; show the login button again:

```ts
const session = await auth.getSession(request);
if (session.status === "expired") {
  // render sign-in
}
```

If you have an exact error code from a response body or a thrown error, look
it up in [Error codes](errors.mdx).