Codex.OAuth (Codex SDK v0.14.0)

Copy Markdown View Source

Native OAuth login and session management for Codex.

Codex.OAuth adds an SDK-managed ChatGPT login path alongside the existing CLI passthrough and API-key flows:

  • storage: :file or :auto writes an upstream-compatible auth.json under the effective CODEX_HOME
  • storage: :memory keeps tokens in memory for host-managed and app-server external auth flows

Flow selection is environment-aware:

  • local desktop prefers browser auth-code + PKCE + loopback callback
  • WSL starts with browser auth, then falls back to device code if the callback does not arrive quickly
  • SSH/headless/container environments prefer device code
  • non-interactive environments never start a login automatically

All OAuth HTTP traffic reuses Codex.Net.CA, so CODEX_CA_CERTIFICATE and SSL_CERT_FILE apply consistently to login and refresh requests.

Summary

Types

flow()

OAuth flow selection.

storage()

OAuth storage strategy.

Functions

authorize_url(opts \\ [])

Returns the authorize URL for a browser-based login attempt.

await_login(pending, opts \\ [])

Waits for a pending login started by begin_login/1 to complete.

begin_login(opts \\ [])

Starts an OAuth login without opening a browser or waiting for completion.

login(opts \\ [])

Ensures a usable OAuth session exists and returns its current status.

logout(opts \\ [])

Removes persisted OAuth auth state and stops any in-memory token store.

open_in_browser(pending, opts \\ [])

Opens a pending browser-based login in the user's external browser.

refresh(opts \\ [])

Refreshes the current OAuth session with the provider token endpoint.

status(opts \\ [])

Reads the current OAuth auth state for the effective CODEX_HOME.

Types

flow()

@type flow() :: :auto | :browser | :browser_code | :device | :device_code

OAuth flow selection.

storage()

@type storage() :: :auto | :file | :memory

OAuth storage strategy.

Functions

authorize_url(opts \\ [])

@spec authorize_url(keyword()) :: {:ok, String.t()} | {:error, term()}

Returns the authorize URL for a browser-based login attempt.

await_login(pending, opts \\ [])

@spec await_login(
  Codex.OAuth.Session.PendingLogin.t()
  | Codex.OAuth.Session.PendingDeviceLogin.t(),
  keyword()
) :: {:ok, Codex.OAuth.LoginResult.t()} | {:error, term()}

Waits for a pending login started by begin_login/1 to complete.

begin_login(opts \\ [])

@spec begin_login(keyword()) ::
  {:ok,
   Codex.OAuth.Session.PendingLogin.t()
   | Codex.OAuth.Session.PendingDeviceLogin.t()}
  | {:error, term()}

Starts an OAuth login without opening a browser or waiting for completion.

Host applications can use this together with open_in_browser/2 and await_login/2 to control the login UX themselves.

login(opts \\ [])

@spec login(keyword()) :: {:ok, Codex.OAuth.LoginResult.t()} | {:error, term()}

Ensures a usable OAuth session exists and returns its current status.

With storage: :file or :auto, this writes upstream-compatible auth state under the effective CODEX_HOME. With storage: :memory, tokens stay in memory only.

logout(opts \\ [])

@spec logout(keyword()) :: :ok | {:error, term()}

Removes persisted OAuth auth state and stops any in-memory token store.

open_in_browser(pending, opts \\ [])

@spec open_in_browser(
  Codex.OAuth.Session.PendingLogin.t(),
  keyword()
) :: :ok | {:error, term()}

Opens a pending browser-based login in the user's external browser.

refresh(opts \\ [])

@spec refresh(keyword()) :: {:ok, Codex.OAuth.Status.t()} | {:error, term()}

Refreshes the current OAuth session with the provider token endpoint.

status(opts \\ [])

@spec status(keyword()) :: {:ok, Codex.OAuth.Status.t()} | {:error, term()}

Reads the current OAuth auth state for the effective CODEX_HOME.