openai-oauth: an OpenAI-compatible endpoint backed by your ChatGPT account

What openai-oauth actually removes from your setup

The project's pitch is narrow and clear: it turns a ChatGPT account into an OpenAI-compatible API. The README describes the result as an "OpenAI-compatible endpoint ready at http://127.0.0.1:10531/v1" and states that no API key is required. That is the whole value proposition. Instead of provisioning a key, tracking spend against a separate billing account, and rotating a secret, you authenticate once through OpenAI's OAuth flow and the CLI serves requests from the credentials it stores.

The audience is therefore specific. It is a developer on a machine where they are already signed in to Codex or willing to sign in, building a local tool, a prototype, or a desktop app. The v2 release notes frame a second audience: application builders who want their users to bring their own ChatGPT accounts, which is what the Sign in with ChatGPT React component is for. The README says that component works across free and paid plans.

Where it is not aimed is shared infrastructure. Everything in the quickstart binds to loopback, the login callback listens on loopback, and the credential store is a per-user directory. Nothing in the README describes a server-side key vault, per-tenant isolation, or a quota layer.

The mechanism: OAuth login, a loopback callback, and a local proxy

There are three moving parts, and the README is explicit about all three.

First, authentication. `npx openai-oauth login` starts a sign-in flow that listens on loopback and uses `http://localhost:1455/auth/callback` as the callback URL, which the README describes as the local callback URL accepted by OpenAI OAuth. Credentials land in `~/.codex`, the same directory the `codex` CLI uses. That shared location is the design decision worth noticing: openai-oauth is not inventing its own credential format, it is reading the same store the Codex CLI already writes. It also means signing out of one affects the other.

Second, the proxy. The CLI binds `127.0.0.1:10531` by default and exposes `/v1/responses`, `/v1/chat/completions` and `/v1/models`. It forwards upstream to `https://chatgpt.com/backend-api/codex`, which is the default for the `--base-url` flag. Streaming responses, tool calls and reasoning traces are listed as supported.

Third, model discovery. `/v1/models` is described as account-aware by default: the CLI discovers the Codex models your account has access to. The `--models` flag overrides that with a comma-separated allowlist, and `--codex-version` overrides the Codex client version used for discovery, defaulting to the latest `@openai/codex` from npm with a bundled fallback. That fallback matters, because discovery depends on an upstream client version the project does not control.

Installing openai-oauth and making a first request

The fastest path is the CLI, run directly from npm with no install step. The README shows this exact invocation:

npx openai-oauth@latest

On success the terminal prints an OpenAI-compatible endpoint, tells you to use it as your OpenAI base URL, and notes that no API key is required. It also lists available models, with examples such as `gpt-5.6-terra`, `gpt-5.6-sol` and `gpt-image-2`. If you are not signed in, the CLI asks you to sign in locally and stores credentials in `~/.codex`.

If you would rather authenticate without starting the server, the README gives a separate command. This one only performs the login:

npx openai-oauth login

For a background process there is a detached mode, and the README documents the companion commands for checking and stopping it:

npx openai-oauth --detach
npx openai-oauth status
npx openai-oauth logs --follow
npx openai-oauth stop

Inside a running foreground session, pressing `d` keeps it running in the background and `q` quits.

For TypeScript code that talks to the account directly, the SDK route installs three packages. The README lists them as `@openai-oauth/local`, `@openai-oauth/ai-sdk` and `ai`:

npm i @openai-oauth/local @openai-oauth/ai-sdk ai

Usage is a factory function plus a credentials helper. The README's example calls `createOpenAIOAuth(openaiCredentials())` and then `generateText` with a model id:

import { createOpenAIOAuth } from "@openai-oauth/ai-sdk";
import { openaiCredentials } from "@openai-oauth/local";
import { generateText } from "ai";

const openai = createOpenAIOAuth(openaiCredentials());

const result = await generateText({
	model: openai("gpt-5.4-mini"),
	prompt: "Hello!",
});

Note the README's own caveat before this block: if you are not signed in to Codex locally, run `npx openai-oauth login` first. The SDK does not perform the sign-in for you.

Sign in with ChatGPT in a web app, and why it needs a browser extension

The v2 headline feature is letting your users bring their own ChatGPT accounts. The README installs four packages for this: `@openai-oauth/react`, `@openai-oauth/ai-sdk`, `ai` and `@ai-sdk/react`.

npm i @openai-oauth/react @openai-oauth/ai-sdk ai @ai-sdk/react

The client side renders a `SignInWithChatGPT` component and passes headers obtained from `openaiAuthHeaders()` into a completion call. The server side reads credentials from the incoming request via `openaiCredentials(request)` from `@openai-oauth/react/server` and streams a response. The README's Next.js example uses `useCompletion` with `streamProtocol: "text"` and a route handler that calls `streamText`.

Here is the part that deserves scrutiny. The README states that first-time users are prompted to install Sign in with ChatGPT for Chrome or Firefox for secure authentication. That is an unusual dependency for a web sign-in: a browser extension sits between your users and the auth flow, and it has to be installed before the flow works. The README describes it as secure authentication, but it does not explain the threat model, what the extension mediates, or what happens on browsers and devices where it cannot be installed. For an internal tool this is a manageable onboarding step. For a public consumer product it is a real drop-off point, and the documentation does not address it.

Supported endpoints, and the limits the README admits to

Three endpoints work: `/v1/responses`, `/v1/chat/completions` and `/v1/models`. Streaming, tool calls and reasoning traces are listed as supported. The README points readers to a Known Limitations section for more, which is the honest place to look before committing.

The structural limitation is upstream dependence. The proxy forwards to `https://chatgpt.com/backend-api/codex`. Model discovery depends on the Codex client version, defaulting to the newest `@openai/codex` on npm. If OpenAI changes what that client can see or how the backend responds, this project has to follow. The `--codex-version` flag exists precisely because that coupling is real.

The second limitation is the credential store. Sharing `~/.codex` with the Codex CLI is convenient on a developer laptop and awkward anywhere else. Any process that can read that directory can use the account. The README does not document a separate credential path, encryption at rest, or a way to scope the stored token.

The third is exposure. The `--host` flag defaults to `127.0.0.1`, and the README warns that non-loopback hosts expose the proxy to your network. There is no mention of an authentication layer in front of the proxy, so binding it to `0.0.0.0` means anyone who can reach the port can spend your account's usage.

openai-oauth compared with a plain API key

The obvious alternative is the standard OpenAI API with an API key. The difference is not cosmetic.

With an API key, the credential is issued for programmatic use, can typically be scoped and revoked independently, and is billed as its own line item. The README's framing of openai-oauth is the inverse: it uses your ChatGPT account, shares credentials with the Codex CLI in `~/.codex`, and requires no key at all. You get access without a separate billing relationship, and you give up the separation that a dedicated key provides.

There is a practical consequence for teams. An API key can be held in a secrets manager and rotated on a schedule. A ChatGPT OAuth credential tied to a person's account cannot be handed to a CI runner without that person's session being the thing CI depends on. For a solo developer prototyping locally, that trade is fine. For a service with an on-call rotation, it is the wrong shape.

The other alternative is the Codex CLI itself. openai-oauth reads the same credential store, so if your workflow is already a terminal agent, the CLI may cover you and the proxy adds nothing. The proxy earns its place when a client speaks the OpenAI HTTP API and you want that client pointed at your account without changing the client.

Licence, maintenance and upgrade cost

The repository is Apache-2.0, and the v2 notes call this out explicitly under the heading Apache-2.0 License, saying the project can be used in both open-source and proprietary applications. That is a permissive licence with an explicit patent grant, and it is a genuine change from whatever terms applied before v2. Read NOTICE alongside LICENSE, since Apache-2.0 projects that ship one usually attach attribution requirements there. This is a description of the files present, not legal advice; if you are redistributing, have counsel read both.

The repository is not archived, and the last push was on 2026-07-15, which is the same day v2.0.0 was released. That is a single data point, not a development cadence. The monorepo layout (packages/, apps/, turbo.json, bun.lock, a `publish:packages` script) shows the project is built and published as a set of versioned npm packages, so upgrading means tracking several package versions together rather than one binary.

The upgrade cost that matters most is not in this repository. Because the proxy tracks an upstream Codex client and an undocumented backend, a breaking change on OpenAI's side can surface as a failed model discovery or a rejected request, and the fix has to come from this project. Budget for the possibility that an upgrade is forced rather than chosen.

Editorial conclusion

Adopt openai-oauth if you already have a ChatGPT account, work on loopback, and want an OpenAI-compatible base URL without managing an API key: `npx openai-oauth@latest` and point your client at http://127.0.0.1:10531/v1. Do not adopt it for shared or multi-tenant production traffic, and do not bind `--host` to a non-loopback interface on a machine you do not control, since the README states that exposes the proxy to your network. Verify first that your account is signed in to Codex, that your client only needs the supported endpoints, and that the credentials written to `~/.codex` are acceptable in your environment.

Frequently asked questions

Official sources

1. EvanZhouDev/openai-oauth on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases