ai-sdk-codex-oauth

Vercel AI SDK provider for the ChatGPT Codex backend. Authenticates via OAuth device code flow using your ChatGPT subscription — no API key needed.

Install

npm install ai-sdk-codex-oauth ai

Quick Start

import { authenticate, createCodexOAuth } from "ai-sdk-codex-oauth";
import { generateText } from "ai";

const auth = await authenticate({
  onUserCode: ({ userCode, verifyUrl }) => {
    console.log(`Go to ${verifyUrl} and enter: ${userCode}`);
  },
  openBrowser: true,
});
const codex = createCodexOAuth({ auth });

const { text } = await generateText({
  model: codex("gpt-5.3-codex"),
  prompt: "Hello!",
});

Browser Usage

In the browser, use LocalStorageTokenStorage to persist tokens across page reloads. On subsequent loads, authenticate() returns immediately if valid tokens are stored.

import { authenticate, createCodexOAuth, LocalStorageTokenStorage } from "ai-sdk-codex-oauth";
import { streamText } from "ai";

const auth = await authenticate({
  storage: new LocalStorageTokenStorage(),
  onUserCode: ({ userCode, verifyUrl }) => {
    // Show the code and link in your UI
    console.log(`Go to ${verifyUrl} and enter: ${userCode}`);
  },
});

const codex = createCodexOAuth({ auth });

const result = streamText({
  model: codex("gpt-5.3-codex"),
  messages: [{ role: "user", content: "Hello!" }],
});

for await (const chunk of result.textStream) {
  console.log(chunk);
}

CORS restriction: The Codex backend only allows browser requests from specific localhost ports: 3000, 5173, and 8000. If your dev server uses a different port, the request will fail with a CORS error. Configure your dev server accordingly (e.g. Vite defaults to 5173, which works).

Authentication

The authenticate() function handles the full auth lifecycle and returns an Auth object that you pass to createCodexOAuth(). It is safe to call on every app start — if valid tokens exist in storage, it returns immediately without any network calls or user interaction.

1. Checks storage for valid, non-expired tokens — returns immediately if found
2. If tokens are expired, attempts a silent refresh
3. Otherwise, initiates the OAuth device code flow (calls onUserCode)

| Option | Required | Description | |---|---|---| | onUserCode | Yes | Callback receiving { userCode, verifyUrl } — display these to the user | | storage | No | TokenStorage instance for persistence (default: in-memory) | | openBrowser | No | Auto-open the verification URL (default: false) | | onStatus | No | Callback for status updates during polling | | signal | No | AbortSignal for cancellation | | timeoutMs | No | Max polling time in ms (default: 5 minutes) |

If openBrowser is true, the library opens the verification URL automatically. In Node.js this requires the open package:

npm install open

Provider Options

const codex = createCodexOAuth({
  // Required: the Auth object returned by authenticate()
  auth,

  // Optional: identifier sent in the `originator` header (default: "ai-sdk-codex-oauth")
  originator: "my-app",
});

System Instructions

The Codex backend requires an instructions field in every request. The middleware defaults to an empty string if none is provided.

The simplest way to give the model system-level context is the standard system param:

const { text } = await generateText({
  model: codex("gpt-5.3-codex"),
  system: "You are a helpful assistant.",
  prompt: "Hello!",
});

This is converted to a developer message in the input array. To set the top-level instructions field instead, use provider options:

const { text } = await generateText({
  model: codex("gpt-5.3-codex"),
  prompt: "Hello!",
  providerOptions: {
    openai: { instructions: "You are a helpful assistant." },
  },
});

For most use cases, system is simpler and sufficient.

Models

| Model | Description | |---|---| | gpt-5.3-codex | Latest Codex model (default) | | gpt-5.2-codex | Previous generation | | gpt-5.1-codex-max | Extended context | | gpt-5.1-codex-mini | Smaller / faster | | gpt-5.2 | Non-Codex variant |

Legacy models (gpt-5.1-codex, gpt-5.1, gpt-5-codex, gpt-5, gpt-5-codex-mini) are also accepted but not advertised. Invalid model IDs throw an error.

Token Storage

The TokenStorage interface has three methods: load(), save(state), and clear(). Built-in implementations:

| Class | Environment | Storage location | |---|---|---| | MemoryStorage | Any | In-process memory (lost on restart) | | LocalStorageTokenStorage | Browser | localStorage | | FileStorage | Node.js | ~/.config/ai-sdk-codex-oauth/auth.json |

Implement TokenStorage for custom backends (database, keychain, etc.).

CORS and Allowed Origins

The Codex backend restricts browser CORS requests to a specific set of localhost ports:

• http://localhost:3000
• http://localhost:5173
• http://localhost:8000

Requests from other origins (including localhost on other ports) will fail with 400 Disallowed CORS origin. This only affects browser apps — Node.js is unaffected.

If you use Vite, its default port (5173) works. Set strictPort: true in your Vite config to avoid silent port incrementing:

// vite.config.ts
export default defineConfig({
  server: { port: 5173, strictPort: true },
});

Codex Backend Constraints

The Codex backend differs from the standard OpenAI API in several ways. The fetch middleware handles these automatically:

• Streaming only — stream is always forced to true
• No storage — store is always forced to false
• Instructions required — defaults to "" if not provided
• No temperature or max_tokens — these parameters are stripped from requests
• Requires a ChatGPT Plus, Pro, or Team subscription

Example App

A browser-based chat app is included in example/:

cd example
npm install
npm run dev

This starts a Vite dev server on port 5173. Log in with your ChatGPT account, pick a model, and chat.

License

MIT