# `Codex.OAuth`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.18.0/lib/codex/oauth.ex#L1)

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.

# `flow`

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

OAuth flow selection.

# `storage`

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

OAuth storage strategy.

# `authorize_url`

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

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

# `await_login`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

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

# `open_in_browser`

```elixir
@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`

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

Refreshes the current OAuth session with the provider token endpoint.

# `status`

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

Reads the current OAuth auth state for the effective `CODEX_HOME`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*