diff --git a/README.md b/README.md
index c32aac1f..107af4bd 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ Realtime: Realtime gateway API service
   * [Shell Completion](#shell-completion)
   * [CLI Example Usage](#cli-example-usage)
   * [Authentication](#authentication)
+  * [Browser sign-in (OAuth2)](#browser-sign-in-oauth2)
   * [Available Commands](#available-commands)
   * [Request Body Input](#request-body-input)
   * [Server Selection](#server-selection)
@@ -75,7 +76,7 @@ Download pre-built binaries for your platform from the [releases page](https://g
 
 ## Quickstart: zero to a talking agent
 
-Runnable end to end by a person or by a coding agent. You need an access token and [`jq`](https://jqlang.org) (used only to pull IDs out of the JSON responses). Create a **personal access token** in Voiceflow under **Settings → Access tokens** (tokens start with `vfp_`; they expire, default 30 days), then:
+Runnable end to end by a person or by a coding agent. You need credentials and [`jq`](https://jqlang.org) (used only to pull IDs out of the JSON responses). At a terminal, `vf auth login` signs you in through the browser and stores the session for you (see [Browser sign-in](#browser-sign-in-oauth2)). For scripts, CI, and coding agents, create a **personal access token** in Voiceflow under **Settings → Access tokens** (tokens start with `vfp_`; they expire, default 30 days), then:
 
 ```bash
 export VF_TOKEN=vfp_...   # every command also accepts --token
@@ -210,6 +211,69 @@ vf configure
 Configuration is stored in `~/.config/vf/config.yaml`.
 <!-- End Authentication [security] -->
 
+<!-- The section below is hand-written; it sits outside the generated markers above so `speakeasy run` does not overwrite it. -->
+## Browser sign-in (OAuth2)
+
+Instead of pasting a personal access token, sign in through the browser:
+
+```bash
+vf auth login
+```
+
+This runs an OAuth2 authorization code flow with PKCE against
+`https://auth-api.voiceflow.com`: the CLI opens your browser, receives the
+authorization code on a loopback listener (`http://127.0.0.1:5133x/oauth/callback`),
+and exchanges it for an access and refresh token. Later commands refresh the
+access token automatically as it nears expiry, so the session keeps working
+without another sign-in.
+
+| Command | What it does |
+|---------|--------------|
+| `vf auth login` | Sign in through the browser |
+| `vf auth login --no-browser` | Print the sign-in URL instead of opening a browser (headless machines) |
+| `vf auth login --token <value>` | Store a bearer token non-interactively, no browser |
+| `vf auth login --manual` | Prompt for a bearer token instead of signing in |
+| `vf auth whoami` | Show the configured credential and the current session |
+| `vf auth logout` | Clear the session and every stored credential |
+
+Other flags: `--scope` (repeatable) requests specific scopes instead of the
+ones the authorization server advertises, and `--login-timeout` bounds the wait
+for the browser (default 5m).
+
+**Signing in over SSH.** `--no-browser` only stops the CLI from launching a
+browser; the callback listener still runs on the *remote* host's loopback
+interface, so a URL opened on your workstation would redirect to your
+workstation instead. Forward the callback port to the remote host first:
+
+```bash
+ssh -L 51330:127.0.0.1:51330 remote-host
+vf auth login --no-browser   # then open the printed URL locally
+```
+
+The CLI binds the first free port of 51330-51333, so forward the port you
+intend it to use and keep the others occupied or unforwarded.
+
+**Where the tokens live.** Access and refresh tokens go to the OS keychain —
+macOS Keychain, Windows Credential Manager, Linux Secret Service — under
+separate entries. On a machine with no keychain (headless Linux, containers)
+they fall back to `~/.config/vf/oauth.json`, written with owner-only
+permissions. Session metadata that is not secret (issuer, scopes, expiry, and
+the cached public client registration) is always kept in
+`~/.config/vf/oauth.json` and `~/.config/vf/oauth-client.json`.
+
+**Precedence.** An active browser session outranks a token stored by
+`vf configure` or `vf auth login --token`, because it is refreshed on demand.
+A `--token` flag or a `VF_TOKEN` environment variable still wins over both, so
+CI keeps behaving exactly as before and agent mode is unaffected —
+`vf auth login` is interactive and stays blocked there.
+
+**Pointing at another authorization server.** `VF_OAUTH_ISSUER`,
+`VF_OAUTH_CLIENT_ID`, `VF_OAUTH_RESOURCE`, `VF_OAUTH_SCOPES`, and
+`VF_OAUTH_REDIRECT_URI` override the defaults. With no `VF_OAUTH_CLIENT_ID`
+set, the CLI registers itself as a public client through the authorization
+server's dynamic client registration endpoint and caches the resulting
+`client_id` for later logins.
+
 <!-- Start Available Commands [operations] -->
 ## Available Commands
 
diff --git a/docs/vf_auth.md b/docs/vf_auth.md
index 892cf2e1..e1865091 100644
--- a/docs/vf_auth.md
+++ b/docs/vf_auth.md
@@ -38,6 +38,6 @@ Subcommands:
 ### SEE ALSO
 
 * [vf](vf.md)	 - Realtime: Realtime gateway API service
-* [vf auth login](vf_auth_login.md)	 - Interactively configure authentication credentials
+* [vf auth login](vf_auth_login.md)	 - Sign in through the browser or configure credentials
 * [vf auth logout](vf_auth_logout.md)	 - Clear all stored authentication credentials
 * [vf auth whoami](vf_auth_whoami.md)	 - Display current authentication configuration
diff --git a/docs/vf_auth_login.md b/docs/vf_auth_login.md
index 9ea7c310..10d43a95 100644
--- a/docs/vf_auth_login.md
+++ b/docs/vf_auth_login.md
@@ -1,15 +1,18 @@
 ## vf auth login
 
-Interactively configure authentication credentials
+Sign in through the browser or configure credentials
 
 ### Synopsis
 
-Interactively configure authentication credentials for vf.
-Secret credentials are stored in the OS keychain when available,
-with a config file fallback.
+Sign in to Voiceflow.
 
-All fields are optional — press Enter to skip any field you don't need.
-Use the configure command for both authentication and global parameters.
+By default this opens your browser to complete an OAuth2 authorization code
+flow, then stores the resulting access and refresh tokens in the OS keychain
+when available, with an owner-only file fallback.
+
+Use --token to store a bearer token non-interactively, or --manual to be
+prompted for one. Use the configure command for both authentication and global
+parameters.
 
 ```
 vf auth login [flags]
@@ -18,7 +21,11 @@ vf auth login [flags]
 ### Options
 
 ```
-  -h, --help   help for login
+  -h, --help                     help for login
+      --login-timeout duration   How long to wait for the browser to complete sign-in (default 5m0s)
+      --manual                   Prompt for a bearer token instead of signing in through the browser
+      --no-browser               Print the sign-in URL instead of opening a browser
+      --scope stringArray        OAuth scope to request (repeatable). Defaults to the scopes the authorization server advertises.
 ```
 
 ### Options inherited from parent commands
diff --git a/go.mod b/go.mod
index 0040a276..d856d22a 100644
--- a/go.mod
+++ b/go.mod
@@ -13,6 +13,7 @@ require (
 	github.com/spf13/pflag v1.0.9
 	github.com/stretchr/testify v1.9.0
 	github.com/zalando/go-keyring v0.2.6
+	golang.org/x/sys v0.41.0
 	golang.org/x/term v0.40.0
 	gopkg.in/yaml.v3 v3.0.1
 )
@@ -51,6 +52,5 @@ require (
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/sync v0.11.0 // indirect
-	golang.org/x/sys v0.41.0 // indirect
 	golang.org/x/text v0.18.0 // indirect
 )
diff --git a/internal/cli/auth.go b/internal/cli/auth.go
index a807a2c6..2a26cb02 100644
--- a/internal/cli/auth.go
+++ b/internal/cli/auth.go
@@ -9,6 +9,7 @@ import (
 	"github.com/charmbracelet/lipgloss"
 	"github.com/spf13/cobra"
 	"github.com/voiceflow/cli/internal/config"
+	"github.com/voiceflow/cli/internal/oauth"
 	"github.com/voiceflow/cli/internal/output"
 	"golang.org/x/term"
 	"os"
@@ -28,17 +29,22 @@ Subcommands:
 	}
 	parent.AddCommand(authCmd)
 
-	authCmd.AddCommand(&cobra.Command{
+	loginCmd := &cobra.Command{
 		Use:   "login",
-		Short: "Interactively configure authentication credentials",
-		Long: `Interactively configure authentication credentials for vf.
-Secret credentials are stored in the OS keychain when available,
-with a config file fallback.
+		Short: "Sign in through the browser or configure credentials",
+		Long: `Sign in to Voiceflow.
+
+By default this opens your browser to complete an OAuth2 authorization code
+flow, then stores the resulting access and refresh tokens in the OS keychain
+when available, with an owner-only file fallback.
 
-All fields are optional — press Enter to skip any field you don't need.
-Use the configure command for both authentication and global parameters.`,
+Use --token to store a bearer token non-interactively, or --manual to be
+prompted for one. Use the configure command for both authentication and global
+parameters.`,
 		RunE: runAuthLoginCmd,
-	})
+	}
+	oauth.AddLoginFlags(loginCmd) // browser login flags; see internal/oauth
+	authCmd.AddCommand(loginCmd)
 
 	authCmd.AddCommand(&cobra.Command{
 		Use:   "whoami",
@@ -83,6 +89,12 @@ func runAuthLoginCmd(cmd *cobra.Command, args []string) error {
 		)
 	}
 
+	// Browser-based OAuth2 login is the default. --token, --manual, and
+	// --no-interactive fall through to the token-entry paths below.
+	if oauth.ShouldUseBrowserLogin(cmd) {
+		return oauth.RunLogin(cmd)
+	}
+
 	cfg := config.GetConfig()
 	if cfg == nil {
 		cfg = &config.Config{}
@@ -161,11 +173,20 @@ func runAuthLogoutCmd(cmd *cobra.Command, args []string) error {
 	}
 	cfg.Security.Token = ""
 
+	// Clear the stored OAuth session as well; see internal/oauth.
+	hadSession, err := oauth.RunLogout()
+	if err != nil {
+		return fmt.Errorf("failed to clear OAuth session: %w", err)
+	}
+
 	if err := config.SaveConfig(cfg); err != nil {
 		return fmt.Errorf("failed to save configuration: %w", err)
 	}
 
 	out := cmd.OutOrStdout()
+	if hadSession {
+		fmt.Fprintln(out, "Signed out of the OAuth session.")
+	}
 	fmt.Fprintln(out, "All authentication credentials have been cleared.")
 	fmt.Fprintf(out, "Configuration saved to %s\n", config.GetConfigPath())
 	return nil
diff --git a/internal/cli/whoami.go b/internal/cli/whoami.go
index 05e18811..75fd0428 100644
--- a/internal/cli/whoami.go
+++ b/internal/cli/whoami.go
@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"github.com/spf13/cobra"
 	"github.com/voiceflow/cli/internal/config"
+	"github.com/voiceflow/cli/internal/oauth"
 	"github.com/voiceflow/cli/internal/usage"
 )
 
@@ -51,5 +52,7 @@ func runWhoamiCmd(cmd *cobra.Command, args []string) error {
 		fmt.Fprintf(out, "  --%-25s [%-7s] %s\n", "token", source, maskSecret(value))
 	}
 
+	oauth.WriteStatus(out) // browser login session; see internal/oauth
+
 	return nil
 }
diff --git a/internal/client/client.go b/internal/client/client.go
index fdeb8eb0..6f270a0c 100644
--- a/internal/client/client.go
+++ b/internal/client/client.go
@@ -4,6 +4,7 @@
 package client
 
 import (
+	"errors"
 	"fmt"
 	"net/http"
 	"strconv"
@@ -12,6 +13,7 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/voiceflow/cli/internal/config"
 	"github.com/voiceflow/cli/internal/flagutil"
+	"github.com/voiceflow/cli/internal/oauth"
 	"github.com/voiceflow/cli/internal/sdk"
 	"github.com/voiceflow/cli/internal/sdk/models/components"
 	"github.com/voiceflow/cli/internal/testclient"
@@ -22,7 +24,11 @@ import (
 // retry configuration, timeout, and test client injection.
 func NewClient(cmd *cobra.Command) (*sdk.VoiceflowSDK, error) {
 	var sdkOpts []sdk.SDKOption
-	sdkOpts = append(sdkOpts, sdk.WithSecurity(buildGlobalSecurity(cmd)))
+	security, err := buildGlobalSecurity(cmd)
+	if err != nil {
+		return nil, err
+	}
+	sdkOpts = append(sdkOpts, sdk.WithSecurity(security))
 	if serverURL := resolveStringFlag(cmd, "server-url"); serverURL != "" {
 		sdkOpts = append(sdkOpts, sdk.WithServerURL(serverURL))
 	} else if serverFlag, _ := flagutil.GetStringFlag(cmd, "server"); serverFlag != "" {
@@ -62,12 +68,29 @@ func resolveStringFlag(cmd *cobra.Command, name string) string {
 
 // buildGlobalSecurity reads security credentials from flags, env vars, and config file.
 // Priority: flag > env var > config file.
-func buildGlobalSecurity(cmd *cobra.Command) components.Security {
+func buildGlobalSecurity(cmd *cobra.Command) (components.Security, error) {
 	// Resolve security credentials: flag > env var > keyring > config file
-	token, _ := config.ResolveSecurityCredential(cmd, "token")
+	token, source := config.ResolveSecurityCredential(cmd, "token")
+
+	// An OAuth session from 'vf auth login' outranks a stored static token —
+	// it is refreshed on demand — while an explicit flag or environment
+	// variable still wins, so CI can override it. See internal/oauth.
+	if source != "flag" && source != "env" {
+		sessionToken, err := oauth.AccessToken(cmd.Context())
+		// Not being signed in is ordinary; a stored session that could not be
+		// renewed is not. Reporting that beats sending the request with a stale
+		// or missing token and surfacing an unrelated API auth failure.
+		if err != nil && !errors.Is(err, oauth.ErrNoSession) {
+			return components.Security{}, err
+		}
+		if sessionToken != "" {
+			token = sessionToken
+		}
+	}
+
 	globalSecurity := components.Security{}
 	if token != "" {
 		globalSecurity.Token = token
 	}
-	return globalSecurity
+	return globalSecurity, nil
 }
diff --git a/internal/oauth/browser.go b/internal/oauth/browser.go
new file mode 100644
index 00000000..a8ea2071
--- /dev/null
+++ b/internal/oauth/browser.go
@@ -0,0 +1,54 @@
+package oauth
+
+import (
+	"fmt"
+	"os/exec"
+	"runtime"
+	"strings"
+)
+
+// browserOpener is swapped out in tests.
+var browserOpener = openBrowser
+
+// openBrowser launches the platform's default browser on url. The URL is
+// always passed as a separate argument, never interpolated into a shell
+// command, so its query string cannot be reinterpreted by a shell.
+func openBrowser(url string) error {
+	var name string
+	var args []string
+
+	switch runtime.GOOS {
+	case "darwin":
+		name, args = "open", []string{url}
+	case "windows":
+		// rundll32 hands the URL to the registered protocol handler without
+		// going through cmd.exe, where '&' would split the command.
+		name, args = "rundll32", []string{"url.dll,FileProtocolHandler", url}
+	default:
+		// xdg-open is the freedesktop standard; the others cover minimal
+		// installs and WSL.
+		for _, candidate := range []string{"xdg-open", "wslview", "gio", "sensible-browser", "x-www-browser"} {
+			if path, err := exec.LookPath(candidate); err == nil {
+				name = path
+				if candidate == "gio" {
+					args = []string{"open", url}
+				} else {
+					args = []string{url}
+				}
+				break
+			}
+		}
+		if name == "" {
+			return fmt.Errorf("no browser launcher found (tried xdg-open, wslview, gio)")
+		}
+	}
+
+	cmd := exec.Command(name, args...)
+	if err := cmd.Start(); err != nil {
+		return fmt.Errorf("launch browser via %s: %w", strings.TrimSpace(name), err)
+	}
+	// The launcher exits immediately after handing the URL to the browser;
+	// reap it so it does not linger as a zombie for the CLI's lifetime.
+	go func() { _ = cmd.Wait() }()
+	return nil
+}
diff --git a/internal/oauth/callback.go b/internal/oauth/callback.go
new file mode 100644
index 00000000..a022e881
--- /dev/null
+++ b/internal/oauth/callback.go
@@ -0,0 +1,180 @@
+package oauth
+
+import (
+	"context"
+	"crypto/subtle"
+	"fmt"
+	"html"
+	"net"
+	"net/http"
+	"sync"
+	"time"
+)
+
+// callbackResult carries the outcome of the authorization redirect back to the
+// login flow.
+type callbackResult struct {
+	code string
+	err  error
+}
+
+// callbackServer is the loopback redirect receiver required by RFC 8252 for
+// native apps: a short-lived HTTP server on 127.0.0.1 that the browser is
+// redirected to with the authorization code.
+type callbackServer struct {
+	listener    net.Listener
+	server      *http.Server
+	results     chan callbackResult
+	redirectURI string
+	state       string
+	once        sync.Once
+}
+
+// startCallbackServer binds the first available address in candidates (each a
+// "host:port" the client is registered to redirect to) and serves path until
+// the authorization code arrives.
+func startCallbackServer(candidates []redirectTarget, state string) (*callbackServer, error) {
+	var listener net.Listener
+	var target redirectTarget
+	var lastErr error
+
+	for _, candidate := range candidates {
+		ln, err := net.Listen("tcp", candidate.address())
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		listener, target = ln, candidate
+		if addr, ok := ln.Addr().(*net.TCPAddr); ok {
+			// Port 0 means "any free port"; record the one actually bound so
+			// the redirect URI matches where the server is listening.
+			target.Port = addr.Port
+		}
+		break
+	}
+	if listener == nil {
+		return nil, fmt.Errorf("no registered callback port is available: %w", lastErr)
+	}
+
+	cb := &callbackServer{
+		listener:    listener,
+		results:     make(chan callbackResult, 1),
+		redirectURI: target.uri(),
+		state:       state,
+	}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc(target.Path, cb.handle)
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		http.NotFound(w, r)
+	})
+
+	cb.server = &http.Server{
+		Handler:           mux,
+		ReadHeaderTimeout: 10 * time.Second,
+	}
+	go func() {
+		// Serve returns ErrServerClosed on shutdown; any other error surfaces
+		// through Wait as a closed connection to the browser.
+		_ = cb.server.Serve(listener)
+	}()
+
+	return cb, nil
+}
+
+// RedirectURI returns the URI the browser will be redirected to.
+func (c *callbackServer) RedirectURI() string { return c.redirectURI }
+
+func (c *callbackServer) handle(w http.ResponseWriter, r *http.Request) {
+	query := r.URL.Query()
+
+	// State is checked before anything else, including an error response: the
+	// loopback ports are predictable, so a stale or unsolicited request could
+	// otherwise win the race and abort a login that is still in flight. A
+	// mismatch is answered but never delivered, leaving the real callback free
+	// to arrive. The comparison is constant-time so the state value cannot
+	// leak through response timing.
+	gotState := query.Get("state")
+	if subtle.ConstantTimeCompare([]byte(gotState), []byte(c.state)) != 1 {
+		c.writePage(w, http.StatusBadRequest, "Login failed", "The login response did not match this session. Start over with 'vf auth login'.")
+		return
+	}
+
+	if errCode := query.Get("error"); errCode != "" {
+		description := query.Get("error_description")
+		message := errCode
+		if description != "" {
+			message = fmt.Sprintf("%s: %s", errCode, description)
+		}
+		c.writePage(w, http.StatusOK, "Login failed", message)
+		c.deliver(callbackResult{err: fmt.Errorf("authorization denied (%s)", message)})
+		return
+	}
+
+	code := query.Get("code")
+	if code == "" {
+		c.writePage(w, http.StatusBadRequest, "Login failed", "The login response contained no authorization code.")
+		c.deliver(callbackResult{err: fmt.Errorf("authorization response contained no code")})
+		return
+	}
+
+	c.writePage(w, http.StatusOK, "Signed in", "You can close this tab and return to your terminal.")
+	c.deliver(callbackResult{code: code})
+}
+
+// deliver sends the first result and ignores any later ones, so a reloaded
+// browser tab cannot overwrite a successful outcome.
+func (c *callbackServer) deliver(result callbackResult) {
+	c.once.Do(func() { c.results <- result })
+}
+
+// Wait blocks until the browser completes the redirect, the context is
+// cancelled, or the deadline passes.
+func (c *callbackServer) Wait(ctx context.Context) (string, error) {
+	select {
+	case result := <-c.results:
+		return result.code, result.err
+	case <-ctx.Done():
+		return "", ctx.Err()
+	}
+}
+
+// Close shuts the server down, allowing in-flight responses a moment to reach
+// the browser.
+func (c *callbackServer) Close() {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+	_ = c.server.Shutdown(ctx)
+}
+
+func (c *callbackServer) writePage(w http.ResponseWriter, status int, heading, message string) {
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-store")
+	w.WriteHeader(status)
+	// The message can include an error_description from the authorization
+	// server, so escape everything before it reaches the page.
+	fmt.Fprintf(w, callbackPageTemplate, html.EscapeString(heading), html.EscapeString(heading), html.EscapeString(message))
+}
+
+// callbackPageTemplate takes the page title, heading, and message, each of
+// which must be HTML-escaped by the caller.
+const callbackPageTemplate = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>%s &middot; Voiceflow CLI</title>
+<style>
+  :root { color-scheme: light dark; }
+  body {
+    font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+    display: flex; align-items: center; justify-content: center;
+    min-height: 100vh; margin: 0; background: Canvas; color: CanvasText;
+  }
+  main { text-align: center; padding: 2rem; max-width: 26rem; }
+  h1 { font-size: 1.25rem; margin: 0 0 0.5rem; }
+  p { margin: 0; opacity: 0.75; line-height: 1.5; }
+</style>
+</head>
+<body><main><h1>%s</h1><p>%s</p></main></body>
+</html>
+`
diff --git a/internal/oauth/callback_test.go b/internal/oauth/callback_test.go
new file mode 100644
index 00000000..977a96c7
--- /dev/null
+++ b/internal/oauth/callback_test.go
@@ -0,0 +1,165 @@
+package oauth
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+)
+
+func startTestCallback(t *testing.T, state string) *callbackServer {
+	t.Helper()
+	// Port 0 lets the OS pick a free port, which keeps concurrent tests apart.
+	cb, err := startCallbackServer([]redirectTarget{{Host: "127.0.0.1", Port: 0, Path: callbackPath}}, state)
+	if err != nil {
+		t.Fatalf("startCallbackServer: %v", err)
+	}
+	t.Cleanup(cb.Close)
+	return cb
+}
+
+func TestCallbackServerReturnsCode(t *testing.T) {
+	cb := startTestCallback(t, "the-state")
+
+	if !strings.HasSuffix(cb.RedirectURI(), callbackPath) {
+		t.Errorf("redirect URI = %q, want it to end in %q", cb.RedirectURI(), callbackPath)
+	}
+	if strings.Contains(cb.RedirectURI(), ":0/") {
+		t.Errorf("redirect URI = %q, want the port actually bound", cb.RedirectURI())
+	}
+
+	go func() {
+		resp, err := http.Get(cb.RedirectURI() + "?code=the-code&state=the-state")
+		if err == nil {
+			io.Copy(io.Discard, resp.Body)
+			resp.Body.Close()
+		}
+	}()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	code, err := cb.Wait(ctx)
+	if err != nil {
+		t.Fatalf("Wait: %v", err)
+	}
+	if code != "the-code" {
+		t.Errorf("code = %q, want the-code", code)
+	}
+}
+
+func TestCallbackServerIgnoresAStateMismatch(t *testing.T) {
+	cb := startTestCallback(t, "the-state")
+
+	// The loopback ports are predictable, so an unsolicited request must not
+	// be able to abort a login that is still waiting for the real redirect.
+	resp, err := http.Get(cb.RedirectURI() + "?code=the-code&state=forged")
+	if err != nil {
+		t.Fatalf("GET callback: %v", err)
+	}
+	io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Errorf("status = %d, want the mismatch rejected in the browser", resp.StatusCode)
+	}
+
+	go func() {
+		resp, err := http.Get(cb.RedirectURI() + "?code=the-code&state=the-state")
+		if err == nil {
+			io.Copy(io.Discard, resp.Body)
+			resp.Body.Close()
+		}
+	}()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	code, err := cb.Wait(ctx)
+	if err != nil {
+		t.Fatalf("Wait: %v, want the legitimate callback to still be accepted", err)
+	}
+	if code != "the-code" {
+		t.Errorf("code = %q, want the-code", code)
+	}
+}
+
+func TestCallbackServerIgnoresAnErrorWithTheWrongState(t *testing.T) {
+	cb := startTestCallback(t, "the-state")
+
+	// An error response is no more trusted than a success one: without a
+	// matching state it must not end the login either.
+	resp, err := http.Get(cb.RedirectURI() + "?error=access_denied&state=forged")
+	if err != nil {
+		t.Fatalf("GET callback: %v", err)
+	}
+	io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+	defer cancel()
+
+	if _, err := cb.Wait(ctx); !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("Wait error = %v, want the login to still be waiting", err)
+	}
+}
+
+func TestCallbackServerSurfacesAuthorizationError(t *testing.T) {
+	cb := startTestCallback(t, "the-state")
+
+	go http.Get(cb.RedirectURI() + "?state=the-state&error=access_denied&error_description=user+said+no")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	_, err := cb.Wait(ctx)
+	if err == nil || !strings.Contains(err.Error(), "access_denied") || !strings.Contains(err.Error(), "user said no") {
+		t.Fatalf("Wait error = %v, want the server's denial reason", err)
+	}
+}
+
+func TestCallbackServerEscapesServerSuppliedText(t *testing.T) {
+	cb := startTestCallback(t, "the-state")
+
+	resp, err := http.Get(cb.RedirectURI() + "?state=the-state&error=access_denied&error_description=" + "%3Cscript%3Ealert(1)%3C/script%3E")
+	if err != nil {
+		t.Fatalf("GET callback: %v", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	if strings.Contains(string(body), "<script>") {
+		t.Errorf("callback page rendered unescaped markup from the query string:\n%s", body)
+	}
+	if !strings.Contains(string(body), "&lt;script&gt;") {
+		t.Errorf("callback page did not escape the description:\n%s", body)
+	}
+}
+
+func TestCallbackServerWaitHonoursContext(t *testing.T) {
+	cb := startTestCallback(t, "the-state")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+
+	if _, err := cb.Wait(ctx); err == nil {
+		t.Fatal("expected Wait to return once the context expires")
+	}
+}
+
+func TestCallbackServerFailsWhenNoPortIsAvailable(t *testing.T) {
+	cb := startTestCallback(t, "the-state")
+	target, err := parseRedirectTarget(cb.RedirectURI())
+	if err != nil {
+		t.Fatalf("parseRedirectTarget: %v", err)
+	}
+
+	if _, err := startCallbackServer([]redirectTarget{target}, "other"); err == nil {
+		t.Fatal("expected binding an occupied port to fail")
+	}
+}
diff --git a/internal/oauth/command.go b/internal/oauth/command.go
new file mode 100644
index 00000000..114aae7b
--- /dev/null
+++ b/internal/oauth/command.go
@@ -0,0 +1,129 @@
+package oauth
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"time"
+
+	"github.com/spf13/cobra"
+	"github.com/voiceflow/cli/internal/config"
+)
+
+// Flag names added to 'vf auth login'.
+const (
+	flagManual       = "manual"
+	flagNoBrowser    = "no-browser"
+	flagScope        = "scope"
+	flagLoginTimeout = "login-timeout"
+)
+
+// AddLoginFlags registers the browser-login flags on 'vf auth login'.
+func AddLoginFlags(cmd *cobra.Command) {
+	flags := cmd.Flags()
+	flags.Bool(flagManual, false, "Prompt for a bearer token instead of signing in through the browser")
+	flags.Bool(flagNoBrowser, false, "Print the sign-in URL instead of opening a browser")
+	flags.StringArray(flagScope, nil, "OAuth scope to request (repeatable). Defaults to the scopes the authorization server advertises.")
+	flags.Duration(flagLoginTimeout, DefaultLoginTimeout, "How long to wait for the browser to complete sign-in")
+
+	for _, name := range []string{flagManual, flagNoBrowser, flagScope, flagLoginTimeout} {
+		_ = flags.SetAnnotation(name, "speakeasy:group", []string{"Authentication"})
+	}
+}
+
+// ShouldUseBrowserLogin reports whether 'vf auth login' should run the OAuth
+// browser flow. Passing --token or --manual selects the token-entry path
+// instead, and --no-interactive rules out both browser and prompt.
+func ShouldUseBrowserLogin(cmd *cobra.Command) bool {
+	if manual, err := cmd.Flags().GetBool(flagManual); err == nil && manual {
+		return false
+	}
+	if noInteractive, err := cmd.Flags().GetBool("no-interactive"); err == nil && noInteractive {
+		return false
+	}
+	if flag := cmd.Flags().Lookup("token"); flag != nil && flag.Changed {
+		return false
+	}
+	return true
+}
+
+// RunLogin executes the browser login flow for 'vf auth login' and reports the
+// resulting session. Progress goes to stderr, matching the rest of the auth
+// commands, so piped output stays clean.
+func RunLogin(cmd *cobra.Command) error {
+	out := cmd.OutOrStderr()
+
+	noBrowser, _ := cmd.Flags().GetBool(flagNoBrowser)
+	scopes, _ := cmd.Flags().GetStringArray(flagScope)
+	timeout, _ := cmd.Flags().GetDuration(flagLoginTimeout)
+
+	session, err := Login(cmd.Context(), os.Getenv, LoginOptions{
+		Scopes:    scopes,
+		NoBrowser: noBrowser,
+		Timeout:   timeout,
+		Out:       out,
+	})
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(out, "\nSigned in to %s\n", session.Issuer)
+	if session.Scope != "" {
+		fmt.Fprintf(out, "  %-9s %s\n", "scopes", session.Scope)
+	}
+	fmt.Fprintf(out, "  %-9s %s\n", "expires", describeExpiry(session.Expiry, time.Now()))
+	fmt.Fprintf(out, "  %-9s %s\n", "storage", session.storageLocation())
+
+	// A token from the environment outranks the session that was just stored,
+	// so say so rather than letting the next command look like it ignored the login.
+	if config.GetEnvValue("token") != "" {
+		fmt.Fprintln(out, "\nNote: VF_TOKEN is set and takes precedence over this session. Unset it to use the OAuth session.")
+	}
+	return nil
+}
+
+// RunLogout clears the stored OAuth session and reports whether there was one.
+func RunLogout() (bool, error) {
+	status := CurrentStatus()
+	if err := Logout(); err != nil {
+		return false, err
+	}
+	return status.LoggedIn, nil
+}
+
+// WriteStatus prints the OAuth session block for 'vf auth whoami'.
+func WriteStatus(w io.Writer) {
+	status := CurrentStatus()
+
+	fmt.Fprintln(w)
+	fmt.Fprintln(w, "OAuth session:")
+	if !status.LoggedIn {
+		fmt.Fprintln(w, "  not signed in (run 'vf auth login')")
+		return
+	}
+
+	fmt.Fprintf(w, "  %-9s %s\n", "issuer", status.Issuer)
+	if status.Scope != "" {
+		fmt.Fprintf(w, "  %-9s %s\n", "scopes", status.Scope)
+	}
+	fmt.Fprintf(w, "  %-9s %s\n", "expires", describeExpiry(status.Expiry, time.Now()))
+	fmt.Fprintf(w, "  %-9s %s\n", "storage", status.Storage)
+}
+
+// describeExpiry renders an expiry as an absolute time plus how far away it
+// is, or notes that the session is expired or has no stated lifetime.
+func describeExpiry(expiry, now time.Time) string {
+	if expiry.IsZero() {
+		return "unknown (server did not state a lifetime)"
+	}
+	stamp := expiry.UTC().Format("2006-01-02 15:04 UTC")
+	remaining := expiry.Sub(now)
+	if remaining <= 0 {
+		return fmt.Sprintf("%s (expired; refreshes on next command)", stamp)
+	}
+	precision := time.Minute
+	if remaining < time.Minute {
+		precision = time.Second
+	}
+	return fmt.Sprintf("%s (in %s)", stamp, remaining.Round(precision))
+}
diff --git a/internal/oauth/command_test.go b/internal/oauth/command_test.go
new file mode 100644
index 00000000..15012763
--- /dev/null
+++ b/internal/oauth/command_test.go
@@ -0,0 +1,116 @@
+package oauth
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+// newLoginTestCmd builds a command carrying the same flags 'vf auth login'
+// has: the root's persistent --token and --no-interactive plus the browser
+// login flags.
+func newLoginTestCmd() *cobra.Command {
+	root := &cobra.Command{Use: "vf"}
+	root.PersistentFlags().String("token", "", "Voiceflow bearer token")
+	root.PersistentFlags().Bool("no-interactive", false, "Disable all interactive features")
+
+	login := &cobra.Command{Use: "login", RunE: func(*cobra.Command, []string) error { return nil }}
+	AddLoginFlags(login)
+	root.AddCommand(login)
+	return root
+}
+
+func TestShouldUseBrowserLogin(t *testing.T) {
+	cases := []struct {
+		name string
+		args []string
+		want bool
+	}{
+		{"no flags", []string{"login"}, true},
+		{"explicit token", []string{"login", "--token", "abc"}, false},
+		{"manual prompt", []string{"login", "--manual"}, false},
+		{"non-interactive", []string{"login", "--no-interactive"}, false},
+		{"browser flags only", []string{"login", "--no-browser"}, true},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			root := newLoginTestCmd()
+			root.SetArgs(tc.args)
+			root.SetOut(&strings.Builder{})
+			root.SetErr(&strings.Builder{})
+
+			executed, err := root.ExecuteC()
+			if err != nil {
+				t.Fatalf("execute %v: %v", tc.args, err)
+			}
+			if got := ShouldUseBrowserLogin(executed); got != tc.want {
+				t.Errorf("ShouldUseBrowserLogin(%v) = %v, want %v", tc.args, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestShouldUseBrowserLoginWithoutTheFlagsRegistered(t *testing.T) {
+	// The generated command must still work if the flags are ever missing.
+	bare := &cobra.Command{Use: "login"}
+	if !ShouldUseBrowserLogin(bare) {
+		t.Error("ShouldUseBrowserLogin should default to the browser flow")
+	}
+}
+
+func TestWriteStatusWithoutASession(t *testing.T) {
+	useTestStore(t, true)
+
+	out := &strings.Builder{}
+	WriteStatus(out)
+
+	if !strings.Contains(out.String(), "not signed in") {
+		t.Errorf("status = %q, want it to report no session", out)
+	}
+}
+
+func TestWriteStatusWithASession(t *testing.T) {
+	useTestStore(t, true)
+	if err := SaveSession(sampleSession()); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+
+	out := &strings.Builder{}
+	WriteStatus(out)
+
+	rendered := out.String()
+	for _, want := range []string{DefaultIssuer, "universal.workspace.read", "OS keychain"} {
+		if !strings.Contains(rendered, want) {
+			t.Errorf("status = %q, want it to mention %q", rendered, want)
+		}
+	}
+	if strings.Contains(rendered, "access-token-value") {
+		t.Errorf("status leaked token material:\n%s", rendered)
+	}
+}
+
+func TestDescribeExpiry(t *testing.T) {
+	now := time.Date(2026, 9, 18, 12, 0, 0, 0, time.UTC)
+
+	cases := []struct {
+		name   string
+		expiry time.Time
+		want   string
+	}{
+		{"unknown", time.Time{}, "unknown"},
+		{"expired", now.Add(-time.Hour), "expired"},
+		{"an hour out", now.Add(time.Hour), "in 1h0m0s"},
+		{"seconds out", now.Add(20 * time.Second), "in 20s"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := describeExpiry(tc.expiry, now); !strings.Contains(got, tc.want) {
+				t.Errorf("describeExpiry(%v) = %q, want it to contain %q", tc.expiry, got, tc.want)
+			}
+		})
+	}
+}
diff --git a/internal/oauth/lock.go b/internal/oauth/lock.go
new file mode 100644
index 00000000..862e50d6
--- /dev/null
+++ b/internal/oauth/lock.go
@@ -0,0 +1,73 @@
+package oauth
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// refreshLockFileName guards the load → refresh → save → cleanup sequence
+// against other CLI processes sharing the same stored session.
+const refreshLockFileName = "oauth.lock"
+
+const (
+	// refreshLockTimeout bounds how long a process waits for a peer that is
+	// already refreshing. A refresh is one HTTP round trip, so a peer holding
+	// the lock this long is stuck rather than busy.
+	refreshLockTimeout = 15 * time.Second
+	// refreshLockPoll is the gap between attempts. The lock is only ever held
+	// for the length of one token request, so polling is cheap.
+	refreshLockPoll = 25 * time.Millisecond
+)
+
+// refreshLockDeadline is when to give up waiting for a peer. It is a variable
+// so tests do not have to wait out refreshLockTimeout.
+var refreshLockDeadline = func() time.Time { return time.Now().Add(refreshLockTimeout) }
+
+// lockRefresh takes an exclusive advisory lock on the store directory's lock
+// file and returns the function that releases it. Commands run in parallel
+// processes against one rotating refresh token, so the whole refresh has to be
+// serialised across processes and not just within one.
+func lockRefresh(ctx context.Context) (func(), error) {
+	dir, err := storeDir()
+	if err != nil {
+		return nil, err
+	}
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		return nil, fmt.Errorf("create %s: %w", dir, err)
+	}
+
+	path := filepath.Join(dir, refreshLockFileName)
+	file, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0600)
+	if err != nil {
+		return nil, fmt.Errorf("open %s: %w", path, err)
+	}
+
+	deadline := refreshLockDeadline()
+	for {
+		locked, err := tryLockFile(file)
+		if err != nil {
+			file.Close()
+			return nil, fmt.Errorf("lock %s: %w", path, err)
+		}
+		if locked {
+			return func() {
+				_ = unlockFile(file)
+				_ = file.Close()
+			}, nil
+		}
+		if time.Now().After(deadline) {
+			file.Close()
+			return nil, fmt.Errorf("timed out waiting for %s", path)
+		}
+
+		select {
+		case <-ctx.Done():
+			file.Close()
+			return nil, ctx.Err()
+		case <-time.After(refreshLockPoll):
+		}
+	}
+}
diff --git a/internal/oauth/lock_test.go b/internal/oauth/lock_test.go
new file mode 100644
index 00000000..1b1698be
--- /dev/null
+++ b/internal/oauth/lock_test.go
@@ -0,0 +1,54 @@
+package oauth
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestLockRefreshExcludesAnotherHolder(t *testing.T) {
+	useTestStore(t, true)
+
+	unlock, err := lockRefresh(context.Background())
+	if err != nil {
+		t.Fatalf("lockRefresh: %v", err)
+	}
+
+	// The lock is held per open file, not per process, so a second acquisition
+	// here contends exactly the way a second CLI process would.
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+	if _, err := lockRefresh(ctx); !errors.Is(err, context.DeadlineExceeded) {
+		t.Errorf("second lockRefresh error = %v, want it to wait for the first to finish", err)
+	}
+
+	unlock()
+
+	waitCtx, waitCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer waitCancel()
+	regained, err := lockRefresh(waitCtx)
+	if err != nil {
+		t.Fatalf("lockRefresh after release: %v", err)
+	}
+	regained()
+}
+
+func TestLockRefreshTimesOutWithoutBlockingForever(t *testing.T) {
+	useTestStore(t, true)
+
+	unlock, err := lockRefresh(context.Background())
+	if err != nil {
+		t.Fatalf("lockRefresh: %v", err)
+	}
+	defer unlock()
+
+	// A peer that never releases must not wedge the command indefinitely.
+	orig := refreshLockDeadline
+	refreshLockDeadline = func() time.Time { return time.Now().Add(50 * time.Millisecond) }
+	t.Cleanup(func() { refreshLockDeadline = orig })
+
+	if _, err := lockRefresh(context.Background()); err == nil {
+		t.Error("lockRefresh succeeded while the lock was held")
+	}
+}
diff --git a/internal/oauth/lock_unix.go b/internal/oauth/lock_unix.go
new file mode 100644
index 00000000..09c8338a
--- /dev/null
+++ b/internal/oauth/lock_unix.go
@@ -0,0 +1,27 @@
+//go:build !windows
+
+package oauth
+
+import (
+	"errors"
+	"os"
+	"syscall"
+)
+
+// tryLockFile takes a non-blocking exclusive flock. The bool reports whether
+// the lock was taken; a lock held by another process is not an error.
+func tryLockFile(file *os.File) (bool, error) {
+	err := syscall.Flock(int(file.Fd()), syscall.LOCK_EX|syscall.LOCK_NB)
+	switch {
+	case err == nil:
+		return true, nil
+	case errors.Is(err, syscall.EWOULDBLOCK):
+		return false, nil
+	default:
+		return false, err
+	}
+}
+
+func unlockFile(file *os.File) error {
+	return syscall.Flock(int(file.Fd()), syscall.LOCK_UN)
+}
diff --git a/internal/oauth/lock_windows.go b/internal/oauth/lock_windows.go
new file mode 100644
index 00000000..d3feef0d
--- /dev/null
+++ b/internal/oauth/lock_windows.go
@@ -0,0 +1,35 @@
+//go:build windows
+
+package oauth
+
+import (
+	"errors"
+	"os"
+
+	"golang.org/x/sys/windows"
+)
+
+// tryLockFile takes a non-blocking exclusive lock on the first byte of the
+// file. The bool reports whether the lock was taken; a lock held by another
+// process is not an error.
+func tryLockFile(file *os.File) (bool, error) {
+	var overlapped windows.Overlapped
+	err := windows.LockFileEx(
+		windows.Handle(file.Fd()),
+		windows.LOCKFILE_EXCLUSIVE_LOCK|windows.LOCKFILE_FAIL_IMMEDIATELY,
+		0, 1, 0, &overlapped,
+	)
+	switch {
+	case err == nil:
+		return true, nil
+	case errors.Is(err, windows.ERROR_LOCK_VIOLATION), errors.Is(err, windows.ERROR_IO_PENDING):
+		return false, nil
+	default:
+		return false, err
+	}
+}
+
+func unlockFile(file *os.File) error {
+	var overlapped windows.Overlapped
+	return windows.UnlockFileEx(windows.Handle(file.Fd()), 0, 1, 0, &overlapped)
+}
diff --git a/internal/oauth/login_test.go b/internal/oauth/login_test.go
new file mode 100644
index 00000000..52534b72
--- /dev/null
+++ b/internal/oauth/login_test.go
@@ -0,0 +1,682 @@
+package oauth
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// fakeAuthServer is a minimal stand-in for the Voiceflow authorization server:
+// discovery, dynamic registration, an authorization endpoint that redirects
+// back to the loopback receiver, and a token endpoint that verifies PKCE.
+type fakeAuthServer struct {
+	*httptest.Server
+
+	mu                sync.Mutex
+	registrations     int
+	clients           map[string][]string // client_id -> registered redirect URIs
+	codes             map[string]pendingCode
+	refreshTokens     map[string]string // refresh token -> client_id
+	issued            int
+	authorizeRequests []url.Values
+	accessTokenTTL    int64
+	rotateRefresh     bool
+}
+
+type pendingCode struct {
+	clientID    string
+	challenge   string
+	redirectURI string
+	scope       string
+}
+
+func newFakeAuthServer(t *testing.T) *fakeAuthServer {
+	t.Helper()
+
+	f := &fakeAuthServer{
+		clients:        map[string][]string{},
+		codes:          map[string]pendingCode{},
+		refreshTokens:  map[string]string{},
+		accessTokenTTL: 3600,
+	}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/.well-known/oauth-authorization-server", f.handleDiscovery)
+	mux.HandleFunc("/register", f.handleRegister)
+	mux.HandleFunc("/authorize", f.handleAuthorize)
+	mux.HandleFunc("/token", f.handleToken)
+
+	f.Server = httptest.NewServer(mux)
+	t.Cleanup(f.Close)
+	return f
+}
+
+func (f *fakeAuthServer) handleDiscovery(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, Metadata{
+		Issuer:                        f.URL,
+		AuthorizationEndpoint:         f.URL + "/authorize",
+		TokenEndpoint:                 f.URL + "/token",
+		RegistrationEndpoint:          f.URL + "/register",
+		ScopesSupported:               []string{"universal.workspace.read", "universal.workspace.write"},
+		GrantTypesSupported:           []string{"authorization_code", "refresh_token"},
+		ResponseTypesSupported:        []string{"code"},
+		CodeChallengeMethodsSupported: []string{"S256"},
+	})
+}
+
+func (f *fakeAuthServer) handleRegister(w http.ResponseWriter, r *http.Request) {
+	var req registrationRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid_client_metadata"})
+		return
+	}
+
+	f.mu.Lock()
+	f.registrations++
+	clientID := fmt.Sprintf("client-%d", f.registrations)
+	f.clients[clientID] = req.RedirectURIs
+	f.mu.Unlock()
+
+	writeJSON(w, http.StatusCreated, registrationResponse{
+		ClientID:         clientID,
+		RedirectURIs:     req.RedirectURIs,
+		ClientIDIssuedAt: 1,
+	})
+}
+
+func (f *fakeAuthServer) handleAuthorize(w http.ResponseWriter, r *http.Request) {
+	query := r.URL.Query()
+
+	f.mu.Lock()
+	f.authorizeRequests = append(f.authorizeRequests, query)
+	registered, known := f.clients[query.Get("client_id")]
+	f.mu.Unlock()
+
+	redirectURI := query.Get("redirect_uri")
+	switch {
+	case !known:
+		http.Error(w, "unknown client", http.StatusBadRequest)
+		return
+	case !contains(registered, redirectURI):
+		http.Error(w, "unregistered redirect_uri", http.StatusBadRequest)
+		return
+	case query.Get("response_type") != "code",
+		query.Get("code_challenge_method") != "S256",
+		query.Get("code_challenge") == "",
+		query.Get("state") == "",
+		query.Get("resource") == "":
+		http.Error(w, "invalid authorization request", http.StatusBadRequest)
+		return
+	}
+
+	f.mu.Lock()
+	f.issued++
+	code := fmt.Sprintf("code-%d", f.issued)
+	f.codes[code] = pendingCode{
+		clientID:    query.Get("client_id"),
+		challenge:   query.Get("code_challenge"),
+		redirectURI: redirectURI,
+		scope:       query.Get("scope"),
+	}
+	f.mu.Unlock()
+
+	location := fmt.Sprintf("%s?code=%s&state=%s", redirectURI, url.QueryEscape(code), url.QueryEscape(query.Get("state")))
+	http.Redirect(w, r, location, http.StatusFound)
+}
+
+func (f *fakeAuthServer) handleToken(w http.ResponseWriter, r *http.Request) {
+	if err := r.ParseForm(); err != nil {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid_request"})
+		return
+	}
+
+	f.mu.Lock()
+	defer f.mu.Unlock()
+
+	var clientID, scope string
+	switch r.PostForm.Get("grant_type") {
+	case "authorization_code":
+		pending, ok := f.codes[r.PostForm.Get("code")]
+		if !ok {
+			writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid_grant"})
+			return
+		}
+		delete(f.codes, r.PostForm.Get("code")) // authorization codes are single use
+		sum := sha256.Sum256([]byte(r.PostForm.Get("code_verifier")))
+		if base64.RawURLEncoding.EncodeToString(sum[:]) != pending.challenge {
+			writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid_grant", "error_description": "PKCE verification failed"})
+			return
+		}
+		if r.PostForm.Get("redirect_uri") != pending.redirectURI {
+			writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid_grant", "error_description": "redirect_uri mismatch"})
+			return
+		}
+		clientID, scope = pending.clientID, pending.scope
+
+	case "refresh_token":
+		owner, ok := f.refreshTokens[r.PostForm.Get("refresh_token")]
+		if !ok {
+			writeJSON(w, http.StatusUnauthorized, map[string]any{"message": "Unauthorized", "statusCode": 401})
+			return
+		}
+		clientID, scope = owner, r.PostForm.Get("scope")
+
+	default:
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "unsupported_grant_type"})
+		return
+	}
+
+	f.issued++
+	accessToken := fmt.Sprintf("access-%d", f.issued)
+	refreshToken := fmt.Sprintf("refresh-%d", f.issued)
+	if !f.rotateRefresh && r.PostForm.Get("grant_type") == "refresh_token" {
+		refreshToken = ""
+	}
+	if refreshToken != "" {
+		f.refreshTokens[refreshToken] = clientID
+	}
+
+	writeJSON(w, http.StatusOK, tokenResponse{
+		AccessToken:  accessToken,
+		RefreshToken: refreshToken,
+		TokenType:    "Bearer",
+		ExpiresIn:    f.accessTokenTTL,
+		Scope:        scope,
+	})
+}
+
+func (f *fakeAuthServer) lastAuthorizeRequest(t *testing.T) url.Values {
+	t.Helper()
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if len(f.authorizeRequests) == 0 {
+		t.Fatal("the authorization endpoint was never called")
+	}
+	return f.authorizeRequests[len(f.authorizeRequests)-1]
+}
+
+func (f *fakeAuthServer) registrationCount() int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.registrations
+}
+
+func writeJSON(w http.ResponseWriter, status int, body any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(body)
+}
+
+func contains(values []string, want string) bool {
+	for _, value := range values {
+		if value == want {
+			return true
+		}
+	}
+	return false
+}
+
+// useFakeBrowser makes the "browser" fetch the authorization URL, which
+// drives the redirect back to the loopback receiver.
+func useFakeBrowser(t *testing.T) {
+	t.Helper()
+	orig := browserOpener
+	browserOpener = func(rawURL string) error {
+		go func() {
+			resp, err := http.Get(rawURL)
+			if err != nil {
+				return
+			}
+			io.Copy(io.Discard, resp.Body)
+			resp.Body.Close()
+		}()
+		return nil
+	}
+	t.Cleanup(func() { browserOpener = orig })
+}
+
+func testEnv(server *fakeAuthServer) func(string) string {
+	return envFunc(map[string]string{
+		envIssuer:   server.URL,
+		envResource: "https://realtime-api.test",
+	})
+}
+
+func TestLoginStoresASessionEndToEnd(t *testing.T) {
+	_, ring := useTestStore(t, true)
+	useTestHTTPClient(t)
+	useFakeBrowser(t)
+	server := newFakeAuthServer(t)
+
+	out := &strings.Builder{}
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+
+	session, err := Login(ctx, testEnv(server), LoginOptions{Out: out, Timeout: 15 * time.Second})
+	if err != nil {
+		t.Fatalf("Login: %v\noutput:\n%s", err, out)
+	}
+
+	if session.AccessToken == "" || session.RefreshToken == "" {
+		t.Errorf("session tokens = %q/%q, want both set", session.AccessToken, session.RefreshToken)
+	}
+	if session.TokenEndpoint != server.URL+"/token" {
+		t.Errorf("token endpoint = %q, want the discovered endpoint", session.TokenEndpoint)
+	}
+	if session.Resource != "https://realtime-api.test" {
+		t.Errorf("resource = %q, want the configured resource indicator", session.Resource)
+	}
+	if ring.get(keyringAccessToken) != session.AccessToken {
+		t.Error("access token was not written to the keychain")
+	}
+
+	authorize := server.lastAuthorizeRequest(t)
+	if authorize.Get("code_challenge_method") != "S256" || authorize.Get("code_challenge") == "" {
+		t.Errorf("authorization request did not use PKCE S256: %v", authorize)
+	}
+	if authorize.Get("resource") != "https://realtime-api.test" {
+		t.Errorf("authorization request resource = %q, want the configured resource", authorize.Get("resource"))
+	}
+	if got := authorize.Get("scope"); got != "universal.workspace.read universal.workspace.write" {
+		t.Errorf("scope = %q, want the scopes the server advertises", got)
+	}
+
+	// The stored session is what later commands read.
+	token, err := AccessToken(context.Background())
+	if err != nil {
+		t.Fatalf("AccessToken: %v", err)
+	}
+	if token != session.AccessToken {
+		t.Errorf("AccessToken = %q, want the freshly stored token %q", token, session.AccessToken)
+	}
+}
+
+func TestLoginRequestsExplicitScopes(t *testing.T) {
+	useTestStore(t, true)
+	useTestHTTPClient(t)
+	useFakeBrowser(t)
+	server := newFakeAuthServer(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+
+	if _, err := Login(ctx, testEnv(server), LoginOptions{Scopes: []string{"universal.workspace.read"}, Timeout: 15 * time.Second}); err != nil {
+		t.Fatalf("Login: %v", err)
+	}
+
+	if got := server.lastAuthorizeRequest(t).Get("scope"); got != "universal.workspace.read" {
+		t.Errorf("scope = %q, want only the requested scope", got)
+	}
+}
+
+func TestLoginReusesTheCachedClientRegistration(t *testing.T) {
+	useTestStore(t, true)
+	useTestHTTPClient(t)
+	useFakeBrowser(t)
+	server := newFakeAuthServer(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	for i := range 2 {
+		if _, err := Login(ctx, testEnv(server), LoginOptions{Timeout: 15 * time.Second}); err != nil {
+			t.Fatalf("Login %d: %v", i+1, err)
+		}
+	}
+
+	if got := server.registrationCount(); got != 1 {
+		t.Errorf("registrations = %d, want the second login to reuse the cached client", got)
+	}
+}
+
+func TestLoginUsesAPreRegisteredClientID(t *testing.T) {
+	useTestStore(t, true)
+	useTestHTTPClient(t)
+	useFakeBrowser(t)
+	server := newFakeAuthServer(t)
+
+	// Pre-register the client out of band, as a deployment with a fixed
+	// client ID would.
+	redirectURIs := defaultRedirectURIs()
+	server.mu.Lock()
+	server.clients["preset-client"] = redirectURIs
+	server.mu.Unlock()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+
+	getenv := envFunc(map[string]string{
+		envIssuer:   server.URL,
+		envResource: "https://realtime-api.test",
+		envClientID: "preset-client",
+	})
+
+	session, err := Login(ctx, getenv, LoginOptions{Timeout: 15 * time.Second})
+	if err != nil {
+		t.Fatalf("Login: %v", err)
+	}
+	if session.ClientID != "preset-client" {
+		t.Errorf("client ID = %q, want the configured client", session.ClientID)
+	}
+	if got := server.registrationCount(); got != 0 {
+		t.Errorf("registrations = %d, want none when a client ID is configured", got)
+	}
+}
+
+func TestLoginRegistersTheConfiguredRedirectURI(t *testing.T) {
+	useTestStore(t, true)
+	useTestHTTPClient(t)
+	useFakeBrowser(t)
+	server := newFakeAuthServer(t)
+
+	redirectURI := freeLoopbackURI(t)
+	getenv := envFunc(map[string]string{
+		envIssuer:      server.URL,
+		envResource:    "https://realtime-api.test",
+		envRedirectURI: redirectURI,
+	})
+
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+
+	if _, err := Login(ctx, getenv, LoginOptions{Timeout: 15 * time.Second}); err != nil {
+		t.Fatalf("Login: %v", err)
+	}
+
+	// The override has to reach both the registration and the redirect the
+	// authorization request asks for, or the server rejects the callback.
+	if got := server.lastAuthorizeRequest(t).Get("redirect_uri"); got != redirectURI {
+		t.Errorf("redirect_uri = %q, want the configured %q", got, redirectURI)
+	}
+	rec, err := loadClient(server.URL)
+	if err != nil {
+		t.Fatalf("loadClient: %v", err)
+	}
+	if rec == nil || len(rec.RedirectURIs) != 1 || rec.RedirectURIs[0] != redirectURI {
+		t.Errorf("registered redirect URIs = %v, want only the configured %q", rec, redirectURI)
+	}
+}
+
+func TestLoginReRegistersWhenTheCachedClientMissesTheRedirectURI(t *testing.T) {
+	useTestStore(t, true)
+	useTestHTTPClient(t)
+	useFakeBrowser(t)
+	server := newFakeAuthServer(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	if _, err := Login(ctx, testEnv(server), LoginOptions{Timeout: 15 * time.Second}); err != nil {
+		t.Fatalf("first Login: %v", err)
+	}
+
+	// The cached registration covers the default ports only, so a login with a
+	// redirect URI override cannot reuse it.
+	redirectURI := freeLoopbackURI(t)
+	getenv := envFunc(map[string]string{
+		envIssuer:      server.URL,
+		envResource:    "https://realtime-api.test",
+		envRedirectURI: redirectURI,
+	})
+	if _, err := Login(ctx, getenv, LoginOptions{Timeout: 15 * time.Second}); err != nil {
+		t.Fatalf("second Login: %v", err)
+	}
+
+	if got := server.registrationCount(); got != 2 {
+		t.Errorf("registrations = %d, want a re-registration for the new redirect URI", got)
+	}
+}
+
+// freeLoopbackURI returns a loopback callback URI on a port that was free a
+// moment ago, for exercising the VF_OAUTH_REDIRECT_URI override.
+func freeLoopbackURI(t *testing.T) string {
+	t.Helper()
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("reserve a port: %v", err)
+	}
+	port := listener.Addr().(*net.TCPAddr).Port
+	listener.Close()
+	return redirectTarget{Host: "127.0.0.1", Port: port, Path: callbackPath}.uri()
+}
+
+func TestLoginTimesOutWaitingForTheBrowser(t *testing.T) {
+	useTestStore(t, true)
+	useTestHTTPClient(t)
+	server := newFakeAuthServer(t)
+
+	// A browser that never completes the redirect.
+	orig := browserOpener
+	browserOpener = func(string) error { return nil }
+	t.Cleanup(func() { browserOpener = orig })
+
+	_, err := Login(context.Background(), testEnv(server), LoginOptions{Timeout: 100 * time.Millisecond})
+	if err == nil || !strings.Contains(err.Error(), "timed out") {
+		t.Fatalf("Login error = %v, want a timeout", err)
+	}
+}
+
+func TestAccessTokenRefreshesAnExpiringSession(t *testing.T) {
+	_, ring := useTestStore(t, true)
+	useTestHTTPClient(t)
+	useFakeBrowser(t)
+	server := newFakeAuthServer(t)
+	server.rotateRefresh = true
+
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+
+	session, err := Login(ctx, testEnv(server), LoginOptions{Timeout: 15 * time.Second})
+	if err != nil {
+		t.Fatalf("Login: %v", err)
+	}
+
+	// Push the stored session inside the refresh window.
+	session.Expiry = time.Now().Add(10 * time.Second)
+	if err := SaveSession(session); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+
+	refreshed, err := AccessToken(context.Background())
+	if err != nil {
+		t.Fatalf("AccessToken: %v", err)
+	}
+	if refreshed == session.AccessToken {
+		t.Error("AccessToken returned the old token instead of refreshing")
+	}
+	if ring.get(keyringAccessToken) != refreshed {
+		t.Error("the refreshed token was not persisted to the keychain")
+	}
+
+	stored, err := LoadSession()
+	if err != nil {
+		t.Fatalf("LoadSession: %v", err)
+	}
+	if stored.RefreshToken == session.RefreshToken {
+		t.Error("the rotated refresh token was not persisted")
+	}
+	if !stored.Expiry.After(time.Now().Add(time.Hour - time.Minute)) {
+		t.Errorf("expiry = %v, want it extended by the refresh", stored.Expiry)
+	}
+}
+
+func TestAccessTokenKeepsTheOldRefreshTokenWhenTheServerDoesNotRotate(t *testing.T) {
+	useTestStore(t, true)
+	useTestHTTPClient(t)
+	useFakeBrowser(t)
+	server := newFakeAuthServer(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+
+	session, err := Login(ctx, testEnv(server), LoginOptions{Timeout: 15 * time.Second})
+	if err != nil {
+		t.Fatalf("Login: %v", err)
+	}
+
+	session.Expiry = time.Now().Add(10 * time.Second)
+	if err := SaveSession(session); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+	if _, err := AccessToken(context.Background()); err != nil {
+		t.Fatalf("AccessToken: %v", err)
+	}
+
+	stored, err := LoadSession()
+	if err != nil {
+		t.Fatalf("LoadSession: %v", err)
+	}
+	if stored.RefreshToken != session.RefreshToken {
+		t.Errorf("refresh token = %q, want the original %q retained", stored.RefreshToken, session.RefreshToken)
+	}
+}
+
+func TestAccessTokenClearsTheSessionWhenTheRefreshTokenIsRejected(t *testing.T) {
+	useTestStore(t, true)
+	useTestHTTPClient(t)
+	server := newFakeAuthServer(t)
+
+	expired := &Session{
+		Issuer:        server.URL,
+		TokenEndpoint: server.URL + "/token",
+		ClientID:      "client-1",
+		Expiry:        time.Now().Add(-time.Hour),
+		AccessToken:   "stale-access",
+		RefreshToken:  "unknown-refresh",
+	}
+	if err := SaveSession(expired); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+
+	if _, err := AccessToken(context.Background()); err == nil || !strings.Contains(err.Error(), "vf auth login") {
+		t.Fatalf("AccessToken error = %v, want a prompt to log in again", err)
+	}
+	if _, err := LoadSession(); !errors.Is(err, ErrNoSession) {
+		t.Errorf("LoadSession error = %v, want the rejected session to have been cleared", err)
+	}
+}
+
+func TestAccessTokenKeepsAValidTokenWhenRefreshFailsTransiently(t *testing.T) {
+	useTestStore(t, true)
+	useTestHTTPClient(t)
+
+	// A token endpoint that is unreachable, standing in for a network blip.
+	unreachable := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
+	endpoint := unreachable.URL + "/token"
+	unreachable.Close()
+
+	session := &Session{
+		Issuer:        "https://auth.test",
+		TokenEndpoint: endpoint,
+		ClientID:      "client-1",
+		// Inside the refresh window but not yet expired.
+		Expiry:       time.Now().Add(30 * time.Second),
+		AccessToken:  "still-valid",
+		RefreshToken: "refresh",
+	}
+	if err := SaveSession(session); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+
+	token, err := AccessToken(context.Background())
+	if err != nil {
+		t.Fatalf("AccessToken: %v", err)
+	}
+	if token != "still-valid" {
+		t.Errorf("AccessToken = %q, want the still-valid token to be reused", token)
+	}
+}
+
+func TestNeedsRefreshWithoutAStatedLifetime(t *testing.T) {
+	// The SDK has no 401-to-refresh retry path, so a token the server gave no
+	// expires_in for still has to be refreshed on a schedule rather than
+	// reused forever.
+	now := time.Now()
+	fresh := &Session{AccessToken: "token", RefreshToken: "refresh", ObtainedAt: now.Add(-time.Minute)}
+	if fresh.needsRefresh(now) {
+		t.Error("a token obtained a minute ago should still be used as is")
+	}
+
+	stale := &Session{AccessToken: "token", RefreshToken: "refresh", ObtainedAt: now.Add(-2 * assumedTokenLifetime)}
+	if !stale.needsRefresh(now) {
+		t.Error("a token past the assumed lifetime should be refreshed")
+	}
+
+	// With nothing to refresh with, reusing the token is the only option.
+	noRefresh := &Session{AccessToken: "token", ObtainedAt: now.Add(-2 * assumedTokenLifetime)}
+	if noRefresh.needsRefresh(now) {
+		t.Error("a session with no refresh token should keep using its access token")
+	}
+}
+
+func TestAccessTokenRefreshesASessionWithNoStatedLifetime(t *testing.T) {
+	useTestStore(t, true)
+	useTestHTTPClient(t)
+	useFakeBrowser(t)
+	server := newFakeAuthServer(t)
+	server.accessTokenTTL = 0 // the server states no expires_in
+	server.rotateRefresh = true
+
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+
+	session, err := Login(ctx, testEnv(server), LoginOptions{Timeout: 15 * time.Second})
+	if err != nil {
+		t.Fatalf("Login: %v", err)
+	}
+	if !session.Expiry.IsZero() {
+		t.Fatalf("expiry = %v, want none recorded without expires_in", session.Expiry)
+	}
+
+	// Age the session past the assumed lifetime.
+	session.ObtainedAt = time.Now().Add(-2 * assumedTokenLifetime)
+	if err := SaveSession(session); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+
+	refreshed, err := AccessToken(context.Background())
+	if err != nil {
+		t.Fatalf("AccessToken: %v", err)
+	}
+	if refreshed == session.AccessToken {
+		t.Error("AccessToken reused a token that is past its assumed lifetime")
+	}
+}
+
+func TestAccessTokenWithoutASession(t *testing.T) {
+	useTestStore(t, true)
+
+	if _, err := AccessToken(context.Background()); !errors.Is(err, ErrNoSession) {
+		t.Errorf("AccessToken error = %v, want ErrNoSession", err)
+	}
+}
+
+func TestLogoutClearsTheSession(t *testing.T) {
+	useTestStore(t, true)
+
+	if err := SaveSession(sampleSession()); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+	if status := CurrentStatus(); !status.LoggedIn {
+		t.Fatal("CurrentStatus reports signed out with a session stored")
+	}
+
+	if err := Logout(); err != nil {
+		t.Fatalf("Logout: %v", err)
+	}
+	if status := CurrentStatus(); status.LoggedIn {
+		t.Error("CurrentStatus still reports a session after logout")
+	}
+}
diff --git a/internal/oauth/metadata.go b/internal/oauth/metadata.go
new file mode 100644
index 00000000..b2f51d6f
--- /dev/null
+++ b/internal/oauth/metadata.go
@@ -0,0 +1,129 @@
+package oauth
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+)
+
+// Metadata is the subset of RFC 8414 authorization server metadata the login
+// flow needs.
+type Metadata struct {
+	Issuer                        string   `json:"issuer"`
+	AuthorizationEndpoint         string   `json:"authorization_endpoint"`
+	TokenEndpoint                 string   `json:"token_endpoint"`
+	RegistrationEndpoint          string   `json:"registration_endpoint"`
+	ScopesSupported               []string `json:"scopes_supported"`
+	GrantTypesSupported           []string `json:"grant_types_supported"`
+	ResponseTypesSupported        []string `json:"response_types_supported"`
+	CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported"`
+}
+
+// fallbackMetadata mirrors the published document at
+// https://auth-api.voiceflow.com/.well-known/oauth-authorization-server and is
+// used only when discovery fails, so a transient blip on the well-known route
+// does not break login.
+var fallbackMetadata = Metadata{
+	Issuer:                        DefaultIssuer,
+	AuthorizationEndpoint:         DefaultIssuer + "/v1alpha1/oauth2/authorize",
+	TokenEndpoint:                 DefaultIssuer + "/v1alpha1/oauth2/token",
+	RegistrationEndpoint:          DefaultIssuer + "/v1alpha1/oauth2/register",
+	ScopesSupported:               []string{"universal.workspace.read", "universal.workspace.write"},
+	GrantTypesSupported:           []string{"authorization_code", "refresh_token"},
+	ResponseTypesSupported:        []string{"code"},
+	CodeChallengeMethodsSupported: []string{"S256"},
+}
+
+// metadataURL builds the well-known discovery URL for an issuer. Per RFC 8414
+// the path component of the issuer is inserted after the well-known segment.
+func metadataURL(issuer string) (string, error) {
+	u, err := url.Parse(strings.TrimSuffix(issuer, "/"))
+	if err != nil || u.Scheme == "" || u.Host == "" {
+		return "", fmt.Errorf("invalid issuer %q", issuer)
+	}
+	path := strings.TrimSuffix(u.Path, "/")
+	u.Path = "/.well-known/oauth-authorization-server" + path
+	return u.String(), nil
+}
+
+// discover fetches authorization server metadata for the issuer. It never
+// fails: a discovery error falls back to the known endpoint layout, which is
+// reported through the returned error for display but still yields usable
+// metadata.
+func discover(ctx context.Context, hc *http.Client, issuer string) (Metadata, error) {
+	md, err := fetchMetadata(ctx, hc, issuer)
+	if err != nil {
+		fb := fallbackMetadata
+		if issuer != DefaultIssuer {
+			// Only the default issuer has a known endpoint layout.
+			return Metadata{}, err
+		}
+		return fb, err
+	}
+	return md, nil
+}
+
+func fetchMetadata(ctx context.Context, hc *http.Client, issuer string) (Metadata, error) {
+	endpoint, err := metadataURL(issuer)
+	if err != nil {
+		return Metadata{}, err
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
+	if err != nil {
+		return Metadata{}, fmt.Errorf("build discovery request: %w", err)
+	}
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := hc.Do(req)
+	if err != nil {
+		return Metadata{}, fmt.Errorf("fetch %s: %w", endpoint, err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return Metadata{}, fmt.Errorf("read %s: %w", endpoint, err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return Metadata{}, fmt.Errorf("discovery at %s returned %s", endpoint, resp.Status)
+	}
+
+	var md Metadata
+	if err := json.Unmarshal(body, &md); err != nil {
+		return Metadata{}, fmt.Errorf("parse discovery document: %w", err)
+	}
+	if md.AuthorizationEndpoint == "" || md.TokenEndpoint == "" {
+		return Metadata{}, fmt.Errorf("discovery document at %s is missing required endpoints", endpoint)
+	}
+	// RFC 8414 §3.3: the issuer in the document must be present and identical
+	// to the one the request was built from. Accepting a missing or different
+	// value would let one server's metadata be persisted as another's.
+	want := strings.TrimSuffix(issuer, "/")
+	if md.Issuer == "" {
+		return Metadata{}, fmt.Errorf("discovery document at %s states no issuer", endpoint)
+	}
+	if strings.TrimSuffix(md.Issuer, "/") != want {
+		return Metadata{}, fmt.Errorf("discovery document at %s is for issuer %q, not %q", endpoint, md.Issuer, want)
+	}
+	return md, nil
+}
+
+// supportsS256 reports whether the server advertises the S256 challenge
+// method. An empty list is treated as supported: RFC 8414 makes the field
+// optional and S256 is mandatory for public native clients.
+func (m Metadata) supportsS256() bool {
+	if len(m.CodeChallengeMethodsSupported) == 0 {
+		return true
+	}
+	for _, method := range m.CodeChallengeMethodsSupported {
+		if strings.EqualFold(method, "S256") {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/oauth/metadata_test.go b/internal/oauth/metadata_test.go
new file mode 100644
index 00000000..67604d3d
--- /dev/null
+++ b/internal/oauth/metadata_test.go
@@ -0,0 +1,217 @@
+package oauth
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+)
+
+func TestMetadataURL(t *testing.T) {
+	cases := map[string]string{
+		"https://auth-api.voiceflow.com":  "https://auth-api.voiceflow.com/.well-known/oauth-authorization-server",
+		"https://auth-api.voiceflow.com/": "https://auth-api.voiceflow.com/.well-known/oauth-authorization-server",
+		// RFC 8414: an issuer path is appended after the well-known segment.
+		"https://example.com/tenant": "https://example.com/.well-known/oauth-authorization-server/tenant",
+	}
+
+	for issuer, want := range cases {
+		got, err := metadataURL(issuer)
+		if err != nil {
+			t.Errorf("metadataURL(%q): %v", issuer, err)
+			continue
+		}
+		if got != want {
+			t.Errorf("metadataURL(%q) = %q, want %q", issuer, got, want)
+		}
+	}
+
+	if _, err := metadataURL("not-a-url"); err == nil {
+		t.Error("expected an error for an issuer that is not an absolute URL")
+	}
+}
+
+// failingTransport makes every request fail, standing in for an unreachable
+// discovery endpoint without touching the network.
+type failingTransport struct{}
+
+func (failingTransport) RoundTrip(*http.Request) (*http.Response, error) {
+	return nil, errors.New("network unreachable")
+}
+
+func TestDiscoverFallsBackForTheDefaultIssuer(t *testing.T) {
+	// A default-issuer discovery failure still yields the published endpoint
+	// layout, alongside the error describing what went wrong.
+	client := &http.Client{Transport: failingTransport{}}
+
+	md, err := discover(context.Background(), client, DefaultIssuer)
+	if err == nil {
+		t.Fatal("expected the discovery failure to be reported")
+	}
+	if md.TokenEndpoint != fallbackMetadata.TokenEndpoint {
+		t.Errorf("token endpoint = %q, want the fallback %q", md.TokenEndpoint, fallbackMetadata.TokenEndpoint)
+	}
+	if md.AuthorizationEndpoint != fallbackMetadata.AuthorizationEndpoint {
+		t.Errorf("authorization endpoint = %q, want the fallback %q", md.AuthorizationEndpoint, fallbackMetadata.AuthorizationEndpoint)
+	}
+}
+
+func TestDiscoverFailsForAnUnknownIssuer(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "nope", http.StatusNotFound)
+	}))
+	defer server.Close()
+
+	md, err := discover(context.Background(), server.Client(), server.URL)
+	if err == nil {
+		t.Fatal("expected discovery against an unknown issuer to fail")
+	}
+	if md.TokenEndpoint != "" {
+		t.Errorf("metadata = %+v, want nothing usable for an unknown issuer", md)
+	}
+}
+
+func TestDiscoverRejectsAnIncompleteDocument(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"issuer":"https://example.com"}`))
+	}))
+	defer server.Close()
+
+	if _, err := fetchMetadata(context.Background(), server.Client(), server.URL); err == nil {
+		t.Error("expected an error when the document names no endpoints")
+	}
+}
+
+func TestDiscoverRejectsAMismatchedIssuer(t *testing.T) {
+	// RFC 8414 §3.3: metadata naming a different issuer must not be trusted,
+	// even though every endpoint in it is well formed.
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"issuer":"https://evil.example.com",` +
+			`"authorization_endpoint":"https://evil.example.com/authorize",` +
+			`"token_endpoint":"https://evil.example.com/token"}`))
+	}))
+	defer server.Close()
+
+	if _, err := fetchMetadata(context.Background(), server.Client(), server.URL); err == nil ||
+		!strings.Contains(err.Error(), "is for issuer") {
+		t.Errorf("fetchMetadata error = %v, want the issuer mismatch rejected", err)
+	}
+}
+
+func TestDiscoverRejectsAMissingIssuer(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"authorization_endpoint":"https://a.test/authorize","token_endpoint":"https://a.test/token"}`))
+	}))
+	defer server.Close()
+
+	if _, err := fetchMetadata(context.Background(), server.Client(), server.URL); err == nil ||
+		!strings.Contains(err.Error(), "states no issuer") {
+		t.Errorf("fetchMetadata error = %v, want the absent issuer rejected", err)
+	}
+}
+
+func TestDiscoverAcceptsATrailingSlashOnTheIssuer(t *testing.T) {
+	var issuer string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprintf(w, `{"issuer":%q,"authorization_endpoint":"%s/authorize","token_endpoint":"%s/token"}`,
+			issuer+"/", issuer, issuer)
+	}))
+	defer server.Close()
+	issuer = server.URL
+
+	if _, err := fetchMetadata(context.Background(), server.Client(), issuer); err != nil {
+		t.Errorf("fetchMetadata: %v, want a trailing slash to be tolerated", err)
+	}
+}
+
+func TestSupportsS256(t *testing.T) {
+	if !(Metadata{}).supportsS256() {
+		t.Error("an unstated challenge method should be treated as S256")
+	}
+	if !(Metadata{CodeChallengeMethodsSupported: []string{"plain", "S256"}}).supportsS256() {
+		t.Error("S256 in the list should be detected")
+	}
+	if (Metadata{CodeChallengeMethodsSupported: []string{"plain"}}).supportsS256() {
+		t.Error("a plain-only server should not be treated as S256 capable")
+	}
+}
+
+func TestAuthorizationURLCarriesEveryRequiredParameter(t *testing.T) {
+	md := Metadata{AuthorizationEndpoint: "https://auth.test/authorize"}
+	raw := authorizationURL(md, "client-1", "http://127.0.0.1:51330/oauth/callback", "the-state", "the-challenge",
+		[]string{"universal.workspace.read", "universal.workspace.write"}, DefaultResource)
+
+	if !strings.HasPrefix(raw, "https://auth.test/authorize?") {
+		t.Fatalf("URL = %q, want it built on the authorization endpoint", raw)
+	}
+
+	query := mustParseQuery(t, raw)
+	want := map[string]string{
+		"response_type":         "code",
+		"client_id":             "client-1",
+		"redirect_uri":          "http://127.0.0.1:51330/oauth/callback",
+		"state":                 "the-state",
+		"code_challenge":        "the-challenge",
+		"code_challenge_method": "S256",
+		"scope":                 "universal.workspace.read universal.workspace.write",
+		"resource":              DefaultResource,
+	}
+	for key, value := range want {
+		if got := query.Get(key); got != value {
+			t.Errorf("%s = %q, want %q", key, got, value)
+		}
+	}
+}
+
+func TestAuthorizationURLKeepsAnExistingQueryString(t *testing.T) {
+	md := Metadata{AuthorizationEndpoint: "https://auth.test/authorize?tenant=acme"}
+	raw := authorizationURL(md, "client-1", "http://127.0.0.1:51330/oauth/callback", "s", "c", nil, "")
+
+	query := mustParseQuery(t, raw)
+	if query.Get("tenant") != "acme" {
+		t.Errorf("URL = %q, want the endpoint's own query parameters preserved", raw)
+	}
+	if query.Get("client_id") != "client-1" {
+		t.Errorf("URL = %q, want the login parameters appended", raw)
+	}
+}
+
+func TestParseRedirectTarget(t *testing.T) {
+	target, err := parseRedirectTarget("http://127.0.0.1:51330/oauth/callback")
+	if err != nil {
+		t.Fatalf("parseRedirectTarget: %v", err)
+	}
+	if target.address() != "127.0.0.1:51330" || target.Path != "/oauth/callback" {
+		t.Errorf("target = %+v, want the host, port, and path split out", target)
+	}
+	if target.uri() != "http://127.0.0.1:51330/oauth/callback" {
+		t.Errorf("uri() = %q, want the original URI", target.uri())
+	}
+
+	for _, raw := range []string{
+		"https://example.com/callback", // not loopback
+		"http://example.com:80/cb",     // not loopback
+		"http://127.0.0.1/cb",          // no port
+	} {
+		if _, err := parseRedirectTarget(raw); err == nil {
+			t.Errorf("parseRedirectTarget(%q) succeeded, want an error", raw)
+		}
+	}
+}
+
+func mustParseQuery(t *testing.T, raw string) url.Values {
+	t.Helper()
+	parsed, err := url.Parse(raw)
+	if err != nil {
+		t.Fatalf("parse %q: %v", raw, err)
+	}
+	return parsed.Query()
+}
diff --git a/internal/oauth/oauth.go b/internal/oauth/oauth.go
new file mode 100644
index 00000000..1c0adb24
--- /dev/null
+++ b/internal/oauth/oauth.go
@@ -0,0 +1,526 @@
+// Package oauth implements browser-based OAuth 2.0 login for the CLI.
+//
+// The flow is the authorization code grant with PKCE (RFC 7636) and a loopback
+// redirect (RFC 8252), which is what the Voiceflow authorization server
+// advertises at https://auth-api.voiceflow.com/.well-known/oauth-authorization-server:
+// response type "code", challenge method "S256", token endpoint auth method
+// "none" (a public client with no secret), and dynamic client registration
+// (RFC 7591). The authorization endpoint additionally requires an RFC 8707
+// "resource" indicator naming the API the token is for.
+//
+// Tokens are stored in the OS keychain (macOS Keychain, Windows Credential
+// Manager, Linux Secret Service) through internal/config, with an owner-only
+// file beside the CLI config as the fallback for machines without one.
+//
+// This package is hand-written and is not regenerated by Speakeasy. The
+// generated commands call into it at four points: auth login, auth logout,
+// whoami, and client construction.
+package oauth
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+const (
+	// DefaultIssuer is the Voiceflow authorization server.
+	DefaultIssuer = "https://auth-api.voiceflow.com"
+	// DefaultResource is the RFC 8707 resource indicator: the API the issued
+	// access token is intended for. It matches the SDK's default server.
+	DefaultResource = "https://realtime-api.voiceflow.com"
+	// clientName is what the authorization server shows on the consent screen.
+	clientName = "Voiceflow CLI"
+	// callbackPath is the loopback path the browser is redirected to.
+	callbackPath = "/oauth/callback"
+
+	// DefaultLoginTimeout bounds how long login waits for the browser.
+	DefaultLoginTimeout = 5 * time.Minute
+	// refreshWindow refreshes an access token this long before it expires,
+	// so a request is never sent with a token that expires mid-flight.
+	refreshWindow = 60 * time.Second
+	// assumedTokenLifetime is how long an access token whose response carried
+	// no expires_in is reused before it is refreshed anyway.
+	assumedTokenLifetime = time.Hour
+)
+
+// Environment overrides, mainly for non-production authorization servers.
+const (
+	envIssuer      = "VF_OAUTH_ISSUER"
+	envClientID    = "VF_OAUTH_CLIENT_ID"
+	envResource    = "VF_OAUTH_RESOURCE"
+	envScopes      = "VF_OAUTH_SCOPES"
+	envRedirectURI = "VF_OAUTH_REDIRECT_URI"
+)
+
+// defaultScopes is used when the authorization server does not advertise its
+// scopes and the caller did not ask for specific ones.
+var defaultScopes = []string{"universal.workspace.read", "universal.workspace.write"}
+
+// callbackPorts are the loopback ports the client registers redirect URIs for.
+// Several are registered so a port already taken by another process (or a
+// second concurrent login) does not block the flow.
+var callbackPorts = []int{51330, 51331, 51332, 51333}
+
+// httpClient is the client used for all authorization server calls. It is a
+// package variable so tests can point it at an httptest server.
+var httpClient = &http.Client{Timeout: 30 * time.Second}
+
+// refreshMu serialises token refreshes within a process.
+var refreshMu sync.Mutex
+
+// redirectTarget is a loopback redirect URI split into its parts, so the
+// listener address and the URI string always stay in sync.
+type redirectTarget struct {
+	Host string
+	Port int
+	Path string
+}
+
+func (r redirectTarget) address() string {
+	return net.JoinHostPort(r.Host, strconv.Itoa(r.Port))
+}
+
+func (r redirectTarget) uri() string {
+	return "http://" + r.address() + r.Path
+}
+
+// parseRedirectTarget parses a loopback redirect URI previously registered
+// with the authorization server.
+func parseRedirectTarget(raw string) (redirectTarget, error) {
+	u, err := url.Parse(raw)
+	if err != nil {
+		return redirectTarget{}, fmt.Errorf("parse redirect URI %q: %w", raw, err)
+	}
+	if u.Scheme != "http" {
+		return redirectTarget{}, fmt.Errorf("redirect URI %q is not a loopback http URI", raw)
+	}
+	host := u.Hostname()
+	if host != "127.0.0.1" && host != "localhost" && host != "::1" {
+		return redirectTarget{}, fmt.Errorf("redirect URI %q is not a loopback address", raw)
+	}
+	port, err := strconv.Atoi(u.Port())
+	if err != nil {
+		return redirectTarget{}, fmt.Errorf("redirect URI %q has no port", raw)
+	}
+	path := u.Path
+	if path == "" {
+		path = "/"
+	}
+	return redirectTarget{Host: host, Port: port, Path: path}, nil
+}
+
+// settings resolves the issuer, resource, and any pre-registered client from
+// the environment.
+type settings struct {
+	Issuer      string
+	ClientID    string
+	Resource    string
+	RedirectURI string
+	Scopes      []string
+}
+
+func settingsFromEnv(getenv func(string) string) settings {
+	s := settings{
+		Issuer:      strings.TrimSuffix(firstNonEmpty(getenv(envIssuer), DefaultIssuer), "/"),
+		ClientID:    getenv(envClientID),
+		Resource:    firstNonEmpty(getenv(envResource), DefaultResource),
+		RedirectURI: getenv(envRedirectURI),
+	}
+	if raw := getenv(envScopes); raw != "" {
+		s.Scopes = strings.Fields(strings.ReplaceAll(raw, ",", " "))
+	}
+	return s
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, v := range values {
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+// LoginOptions configures a login attempt.
+type LoginOptions struct {
+	// Scopes requested at the authorization endpoint. Empty means the scopes
+	// the server advertises, falling back to defaultScopes.
+	Scopes []string
+	// NoBrowser prints the authorization URL instead of opening a browser,
+	// for machines without a desktop. Over SSH the callback still lands on the
+	// remote host's loopback interface, so the port has to be forwarded.
+	NoBrowser bool
+	// Timeout bounds the wait for the browser redirect. Zero means
+	// DefaultLoginTimeout.
+	Timeout time.Duration
+	// Out receives progress messages. Nil discards them.
+	Out io.Writer
+}
+
+// Login runs the authorization code flow and stores the resulting session.
+func Login(ctx context.Context, getenv func(string) string, opts LoginOptions) (*Session, error) {
+	out := opts.Out
+	if out == nil {
+		out = io.Discard
+	}
+	timeout := opts.Timeout
+	if timeout <= 0 {
+		timeout = DefaultLoginTimeout
+	}
+
+	cfg := settingsFromEnv(getenv)
+
+	md, err := discover(ctx, httpClient, cfg.Issuer)
+	if err != nil {
+		if md.TokenEndpoint == "" {
+			return nil, fmt.Errorf("discover authorization server: %w", err)
+		}
+		fmt.Fprintf(out, "Warning: could not read authorization server metadata (%v); using known endpoints.\n", err)
+	}
+	if !md.supportsS256() {
+		return nil, fmt.Errorf("authorization server at %s does not support PKCE S256", md.Issuer)
+	}
+
+	client, err := resolveClient(ctx, md, cfg)
+	if err != nil {
+		return nil, err
+	}
+
+	state, err := randomURLSafe(32)
+	if err != nil {
+		return nil, err
+	}
+	verifier, err := newPKCE()
+	if err != nil {
+		return nil, err
+	}
+
+	callback, client, err := listen(ctx, md, cfg, client, state)
+	if err != nil {
+		return nil, err
+	}
+	defer callback.Close()
+
+	scopes := opts.Scopes
+	if len(scopes) == 0 {
+		scopes = cfg.Scopes
+	}
+	if len(scopes) == 0 {
+		scopes = md.ScopesSupported
+	}
+	if len(scopes) == 0 {
+		scopes = defaultScopes
+	}
+
+	authURL := authorizationURL(md, client.ClientID, callback.RedirectURI(), state, verifier.challenge, scopes, cfg.Resource)
+
+	if opts.NoBrowser {
+		fmt.Fprintf(out, "Open this URL to sign in:\n\n  %s\n\n", authURL)
+	} else if err := browserOpener(authURL); err != nil {
+		fmt.Fprintf(out, "Could not open a browser (%v).\nOpen this URL to sign in:\n\n  %s\n\n", err, authURL)
+	} else {
+		fmt.Fprintf(out, "Opening your browser to sign in.\nIf it did not open, use this URL:\n\n  %s\n\n", authURL)
+	}
+	fmt.Fprintln(out, "Waiting for the browser to complete sign-in...")
+
+	waitCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	code, err := callback.Wait(waitCtx)
+	if err != nil {
+		if errors.Is(err, context.DeadlineExceeded) {
+			return nil, fmt.Errorf("timed out after %s waiting for the browser to complete sign-in", timeout)
+		}
+		return nil, err
+	}
+
+	tok, err := exchangeCode(ctx, httpClient, md, client.ClientID, code, verifier.verifier, callback.RedirectURI(), cfg.Resource)
+	if err != nil {
+		return nil, fmt.Errorf("exchange authorization code: %w", err)
+	}
+
+	now := time.Now()
+	session := &Session{
+		Issuer:        md.Issuer,
+		TokenEndpoint: md.TokenEndpoint,
+		ClientID:      client.ClientID,
+		Resource:      cfg.Resource,
+		Scope:         firstNonEmpty(tok.Scope, strings.Join(scopes, " ")),
+		TokenType:     firstNonEmpty(tok.TokenType, "Bearer"),
+		Expiry:        tok.expiry(now),
+		ObtainedAt:    now,
+		AccessToken:   tok.AccessToken,
+		RefreshToken:  tok.RefreshToken,
+	}
+	if err := SaveSession(session); err != nil {
+		return nil, fmt.Errorf("store session: %w", err)
+	}
+	return session, nil
+}
+
+// resolveClient returns the OAuth client to authorize with: an explicitly
+// configured one, the cached dynamic registration, or a fresh registration.
+func resolveClient(ctx context.Context, md Metadata, cfg settings) (*clientRecord, error) {
+	redirectURIs := wantedRedirectURIs(cfg)
+
+	if cfg.ClientID != "" {
+		return &clientRecord{Issuer: md.Issuer, ClientID: cfg.ClientID, RedirectURIs: redirectURIs}, nil
+	}
+
+	cached, err := loadClient(md.Issuer)
+	if err != nil {
+		return nil, err
+	}
+	// A cached registration is only usable if it covers the redirect URIs this
+	// login needs; VF_OAUTH_REDIRECT_URI may have changed since it was cached.
+	if cached != nil && coversRedirectURIs(cached.RedirectURIs, redirectURIs) {
+		return cached, nil
+	}
+
+	registered, err := registerClient(ctx, httpClient, md, clientName, redirectURIs)
+	if err != nil {
+		return nil, err
+	}
+	if err := saveClient(registered); err != nil {
+		return nil, fmt.Errorf("cache client registration: %w", err)
+	}
+	return registered, nil
+}
+
+// wantedRedirectURIs is the redirect URI list this login needs registered:
+// the VF_OAUTH_REDIRECT_URI override when set, otherwise the fixed loopback
+// ports.
+func wantedRedirectURIs(cfg settings) []string {
+	if cfg.RedirectURI != "" {
+		return []string{cfg.RedirectURI}
+	}
+	return defaultRedirectURIs()
+}
+
+// coversRedirectURIs reports whether every wanted URI is already registered.
+func coversRedirectURIs(registered, wanted []string) bool {
+	if len(wanted) == 0 {
+		return false
+	}
+	have := make(map[string]struct{}, len(registered))
+	for _, uri := range registered {
+		have[uri] = struct{}{}
+	}
+	for _, uri := range wanted {
+		if _, ok := have[uri]; !ok {
+			return false
+		}
+	}
+	return true
+}
+
+func defaultRedirectURIs() []string {
+	uris := make([]string, 0, len(callbackPorts))
+	for _, port := range callbackPorts {
+		uris = append(uris, redirectTarget{Host: "127.0.0.1", Port: port, Path: callbackPath}.uri())
+	}
+	return uris
+}
+
+// listen starts the loopback receiver on one of the client's registered
+// redirect URIs. If every registered port is busy it registers a new client on
+// an ephemeral port, since the authorization server rejects a redirect URI the
+// client is not registered for.
+func listen(ctx context.Context, md Metadata, cfg settings, client *clientRecord, state string) (*callbackServer, *clientRecord, error) {
+	targets := make([]redirectTarget, 0, len(client.RedirectURIs))
+	for _, raw := range client.RedirectURIs {
+		target, err := parseRedirectTarget(raw)
+		if err != nil {
+			continue // a non-loopback URI cannot host the receiver
+		}
+		targets = append(targets, target)
+	}
+	if len(targets) == 0 {
+		return nil, nil, fmt.Errorf("client %s has no loopback redirect URI to listen on", client.ClientID)
+	}
+
+	callback, err := startCallbackServer(targets, state)
+	if err == nil {
+		return callback, client, nil
+	}
+	if cfg.ClientID != "" {
+		// A pre-registered client cannot have new redirect URIs added here.
+		return nil, nil, err
+	}
+	if cfg.RedirectURI != "" {
+		// The caller pinned the callback address, so falling back to an
+		// ephemeral port would ignore what they configured.
+		return nil, nil, fmt.Errorf("%s is set to %s, which is not available: %w", envRedirectURI, cfg.RedirectURI, err)
+	}
+
+	// Ephemeral port, then register that exact URI.
+	callback, ephemeralErr := startCallbackServer([]redirectTarget{{Host: "127.0.0.1", Port: 0, Path: callbackPath}}, state)
+	if ephemeralErr != nil {
+		return nil, nil, fmt.Errorf("%w (and no ephemeral port was available: %v)", err, ephemeralErr)
+	}
+
+	registered, regErr := registerClient(ctx, httpClient, md, clientName, append(defaultRedirectURIs(), callback.RedirectURI()))
+	if regErr != nil {
+		callback.Close()
+		return nil, nil, regErr
+	}
+	if err := saveClient(registered); err != nil {
+		callback.Close()
+		return nil, nil, fmt.Errorf("cache client registration: %w", err)
+	}
+	return callback, registered, nil
+}
+
+func authorizationURL(md Metadata, clientID, redirectURI, state, challenge string, scopes []string, resource string) string {
+	params := url.Values{
+		"response_type":         {"code"},
+		"client_id":             {clientID},
+		"redirect_uri":          {redirectURI},
+		"state":                 {state},
+		"code_challenge":        {challenge},
+		"code_challenge_method": {"S256"},
+	}
+	if len(scopes) > 0 {
+		params.Set("scope", strings.Join(scopes, " "))
+	}
+	if resource != "" {
+		// RFC 8707: the authorization server requires the audience the token
+		// is being requested for.
+		params.Set("resource", resource)
+	}
+
+	separator := "?"
+	if strings.Contains(md.AuthorizationEndpoint, "?") {
+		separator = "&"
+	}
+	return md.AuthorizationEndpoint + separator + params.Encode()
+}
+
+// AccessToken returns a valid access token for the stored session, refreshing
+// it when it is expired or about to expire. It returns ErrNoSession when the
+// user is not logged in.
+func AccessToken(ctx context.Context) (string, error) {
+	refreshMu.Lock()
+	defer refreshMu.Unlock()
+
+	// CLI commands routinely run as parallel processes against one stored,
+	// rotating refresh token, so the whole load → refresh → save → cleanup
+	// sequence is serialised across processes too. Without it both processes
+	// load the same refresh token, and the loser's invalid_grant would delete
+	// the session the winner just stored. A lock that cannot be taken is not
+	// fatal: the refresh still runs, only without the cross-process guarantee.
+	if unlock, err := lockRefresh(ctx); err == nil {
+		defer unlock()
+	}
+
+	session, err := LoadSession()
+	if err != nil {
+		return "", err
+	}
+
+	now := time.Now()
+	if !session.needsRefresh(now) {
+		return session.AccessToken, nil
+	}
+	if session.RefreshToken == "" {
+		_ = ClearSession()
+		return "", fmt.Errorf("OAuth session expired; run 'vf auth login'")
+	}
+
+	tok, err := refreshTokens(ctx, httpClient, session.TokenEndpoint, session.ClientID, session.RefreshToken, session.Scope, session.Resource)
+	if err != nil {
+		var tokErr *tokenError
+		if errors.As(err, &tokErr) && tokErr.isInvalidGrant() {
+			_ = ClearSession()
+			return "", fmt.Errorf("OAuth session is no longer valid; run 'vf auth login'")
+		}
+		// A transient failure should not break a command whose token is still
+		// inside its lifetime.
+		if !session.expired(now) {
+			return session.AccessToken, nil
+		}
+		return "", fmt.Errorf("refresh OAuth session: %w", err)
+	}
+
+	session.AccessToken = tok.AccessToken
+	if tok.RefreshToken != "" {
+		// The server rotates refresh tokens; keep the previous one otherwise.
+		session.RefreshToken = tok.RefreshToken
+	}
+	if tok.Scope != "" {
+		session.Scope = tok.Scope
+	}
+	if tok.TokenType != "" {
+		session.TokenType = tok.TokenType
+	}
+	session.Expiry = tok.expiry(now)
+	session.ObtainedAt = now
+
+	// A refreshed token that could not be persisted is still usable for this
+	// command, so a storage failure must not fail the request.
+	_ = SaveSession(session)
+	return session.AccessToken, nil
+}
+
+// needsRefresh reports whether the access token is expired or close enough to
+// expiry to be refreshed first.
+func (s *Session) needsRefresh(now time.Time) bool {
+	if s.AccessToken == "" {
+		return true
+	}
+	if s.Expiry.IsZero() {
+		// The server stated no lifetime. The SDK has no 401-to-refresh retry
+		// path, so a token left alone here would be reused forever once it
+		// expires; refresh it on an assumed lifetime instead. With no refresh
+		// token there is nothing to do but keep using it.
+		return s.RefreshToken != "" && now.Sub(s.ObtainedAt) >= assumedTokenLifetime
+	}
+	return now.After(s.Expiry.Add(-refreshWindow))
+}
+
+func (s *Session) expired(now time.Time) bool {
+	return !s.Expiry.IsZero() && now.After(s.Expiry)
+}
+
+// Logout clears the stored session. The authorization server publishes no
+// revocation endpoint, so this removes the local credentials only.
+func Logout() error {
+	return ClearSession()
+}
+
+// Status describes the stored session for 'vf auth whoami'.
+type Status struct {
+	LoggedIn bool
+	Issuer   string
+	ClientID string
+	Scope    string
+	Storage  string
+	Expiry   time.Time
+	Expired  bool
+}
+
+// CurrentStatus reports the stored session without refreshing it.
+func CurrentStatus() Status {
+	session, err := LoadSession()
+	if err != nil || session == nil {
+		return Status{}
+	}
+	return Status{
+		LoggedIn: true,
+		Issuer:   session.Issuer,
+		ClientID: session.ClientID,
+		Scope:    session.Scope,
+		Storage:  session.storageLocation(),
+		Expiry:   session.Expiry,
+		Expired:  session.expired(time.Now()),
+	}
+}
diff --git a/internal/oauth/pkce.go b/internal/oauth/pkce.go
new file mode 100644
index 00000000..5c74b439
--- /dev/null
+++ b/internal/oauth/pkce.go
@@ -0,0 +1,39 @@
+package oauth
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"fmt"
+)
+
+// randomURLSafe returns n cryptographically random bytes encoded as an
+// unpadded base64url string.
+func randomURLSafe(n int) (string, error) {
+	buf := make([]byte, n)
+	if _, err := rand.Read(buf); err != nil {
+		return "", fmt.Errorf("generate random value: %w", err)
+	}
+	return base64.RawURLEncoding.EncodeToString(buf), nil
+}
+
+// pkce holds an RFC 7636 code verifier and its S256 challenge. The
+// authorization server advertises S256 as the only supported method, so the
+// plain method is deliberately not implemented.
+type pkce struct {
+	verifier  string
+	challenge string
+}
+
+func newPKCE() (pkce, error) {
+	// 32 random bytes encode to 43 characters, the shortest verifier RFC 7636 allows.
+	verifier, err := randomURLSafe(32)
+	if err != nil {
+		return pkce{}, err
+	}
+	sum := sha256.Sum256([]byte(verifier))
+	return pkce{
+		verifier:  verifier,
+		challenge: base64.RawURLEncoding.EncodeToString(sum[:]),
+	}, nil
+}
diff --git a/internal/oauth/pkce_test.go b/internal/oauth/pkce_test.go
new file mode 100644
index 00000000..19e4eb80
--- /dev/null
+++ b/internal/oauth/pkce_test.go
@@ -0,0 +1,38 @@
+package oauth
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"testing"
+)
+
+func TestNewPKCEProducesS256Challenge(t *testing.T) {
+	p, err := newPKCE()
+	if err != nil {
+		t.Fatalf("newPKCE: %v", err)
+	}
+
+	if len(p.verifier) < 43 || len(p.verifier) > 128 {
+		t.Errorf("verifier length %d outside the range RFC 7636 allows", len(p.verifier))
+	}
+
+	sum := sha256.Sum256([]byte(p.verifier))
+	want := base64.RawURLEncoding.EncodeToString(sum[:])
+	if p.challenge != want {
+		t.Errorf("challenge = %q, want S256 of the verifier (%q)", p.challenge, want)
+	}
+}
+
+func TestNewPKCEIsUniquePerCall(t *testing.T) {
+	seen := map[string]bool{}
+	for range 16 {
+		p, err := newPKCE()
+		if err != nil {
+			t.Fatalf("newPKCE: %v", err)
+		}
+		if seen[p.verifier] {
+			t.Fatalf("verifier %q generated twice", p.verifier)
+		}
+		seen[p.verifier] = true
+	}
+}
diff --git a/internal/oauth/register.go b/internal/oauth/register.go
new file mode 100644
index 00000000..59513007
--- /dev/null
+++ b/internal/oauth/register.go
@@ -0,0 +1,101 @@
+package oauth
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+)
+
+// registrationRequest is an RFC 7591 dynamic client registration request for a
+// native, public client using the authorization code flow with PKCE.
+type registrationRequest struct {
+	ClientName              string   `json:"client_name"`
+	RedirectURIs            []string `json:"redirect_uris"`
+	GrantTypes              []string `json:"grant_types"`
+	ResponseTypes           []string `json:"response_types"`
+	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method"`
+	ApplicationType         string   `json:"application_type"`
+}
+
+type registrationResponse struct {
+	ClientID         string   `json:"client_id"`
+	ClientSecret     string   `json:"client_secret"`
+	RedirectURIs     []string `json:"redirect_uris"`
+	ClientIDIssuedAt int64    `json:"client_id_issued_at"`
+	Error            string   `json:"error"`
+	ErrorDescription string   `json:"error_description"`
+	Message          string   `json:"message"`
+}
+
+// registerClient registers a public client for the given redirect URIs and
+// returns the issued client_id. The authorization server advertises
+// token_endpoint_auth_method "none", so no client secret is issued or stored.
+func registerClient(ctx context.Context, hc *http.Client, md Metadata, clientName string, redirectURIs []string) (*clientRecord, error) {
+	if md.RegistrationEndpoint == "" {
+		return nil, fmt.Errorf("authorization server does not support dynamic client registration; set %s to a pre-registered client ID", envClientID)
+	}
+
+	payload, err := json.Marshal(registrationRequest{
+		ClientName:              clientName,
+		RedirectURIs:            redirectURIs,
+		GrantTypes:              []string{"authorization_code", "refresh_token"},
+		ResponseTypes:           []string{"code"},
+		TokenEndpointAuthMethod: "none",
+		ApplicationType:         "native",
+	})
+	if err != nil {
+		return nil, fmt.Errorf("encode registration request: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, md.RegistrationEndpoint, bytes.NewReader(payload))
+	if err != nil {
+		return nil, fmt.Errorf("build registration request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := hc.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("register client: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, fmt.Errorf("read registration response: %w", err)
+	}
+
+	var out registrationResponse
+	if err := json.Unmarshal(body, &out); err != nil {
+		return nil, fmt.Errorf("parse registration response: %w", err)
+	}
+	if resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {
+		switch {
+		case out.ErrorDescription != "":
+			return nil, fmt.Errorf("register client: %s", out.ErrorDescription)
+		case out.Error != "":
+			return nil, fmt.Errorf("register client: %s", out.Error)
+		case out.Message != "":
+			return nil, fmt.Errorf("register client: %s", out.Message)
+		default:
+			return nil, fmt.Errorf("register client: %s", resp.Status)
+		}
+	}
+	if out.ClientID == "" {
+		return nil, fmt.Errorf("register client: response contained no client_id")
+	}
+
+	registered := out.RedirectURIs
+	if len(registered) == 0 {
+		registered = redirectURIs
+	}
+	return &clientRecord{
+		Issuer:       md.Issuer,
+		ClientID:     out.ClientID,
+		RedirectURIs: registered,
+		IssuedAt:     out.ClientIDIssuedAt,
+	}, nil
+}
diff --git a/internal/oauth/store.go b/internal/oauth/store.go
new file mode 100644
index 00000000..366e0446
--- /dev/null
+++ b/internal/oauth/store.go
@@ -0,0 +1,282 @@
+package oauth
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/voiceflow/cli/internal/config"
+	"github.com/zalando/go-keyring"
+)
+
+// ErrNoSession is returned when no OAuth session has been stored, or when the
+// stored session was cleared by logout.
+var ErrNoSession = errors.New("no OAuth session; run 'vf auth login'")
+
+// Keyring entry names. Access and refresh tokens are stored under separate
+// keys rather than as one blob: the Windows Credential Manager caps a
+// credential at 2560 bytes, and a JWT pair can exceed that together.
+const (
+	keyringAccessToken  = "oauth-access-token"
+	keyringRefreshToken = "oauth-refresh-token"
+)
+
+const (
+	sessionFileName = "oauth.json"
+	clientFileName  = "oauth-client.json"
+	sessionVersion  = 1
+)
+
+// Session is a stored OAuth session: the tokens plus everything needed to
+// refresh them without re-running discovery.
+type Session struct {
+	Version       int       `json:"version"`
+	Issuer        string    `json:"issuer"`
+	TokenEndpoint string    `json:"token_endpoint"`
+	ClientID      string    `json:"client_id"`
+	Resource      string    `json:"resource,omitempty"`
+	Scope         string    `json:"scope,omitempty"`
+	TokenType     string    `json:"token_type,omitempty"`
+	Expiry        time.Time `json:"expiry,omitempty"`
+	ObtainedAt    time.Time `json:"obtained_at,omitempty"`
+
+	// TokensInKeyring records where the secrets live. When true the token
+	// fields below are empty on disk and the values come from the OS keychain.
+	TokensInKeyring bool `json:"tokens_in_keyring"`
+
+	AccessToken  string `json:"access_token,omitempty"`
+	RefreshToken string `json:"refresh_token,omitempty"`
+}
+
+// clientRecord caches a dynamic client registration (RFC 7591) so repeat
+// logins reuse the same public client_id. It holds no secret: the
+// authorization server issues public clients with no client_secret.
+type clientRecord struct {
+	Issuer       string   `json:"issuer"`
+	ClientID     string   `json:"client_id"`
+	RedirectURIs []string `json:"redirect_uris"`
+	IssuedAt     int64    `json:"client_id_issued_at,omitempty"`
+}
+
+// Indirection points so tests can run against a temp directory and a fake
+// keychain instead of the real ones.
+var (
+	storeDir         = defaultStoreDir
+	keyringAvailable = config.KeyringAvailable
+	keyringGet       = config.GetKeyringValue
+	keyringSet       = config.SetKeyringValue
+	keyringDelete    = config.DeleteKeyringValue
+)
+
+// defaultStoreDir returns the directory holding the CLI's config file, so
+// OAuth state sits beside it (~/.config/vf on Unix and macOS,
+// %USERPROFILE%\.config\vf on Windows).
+func defaultStoreDir() (string, error) {
+	if path := config.GetConfigPath(); path != "" {
+		return filepath.Dir(path), nil
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("locate home directory: %w", err)
+	}
+	return filepath.Join(home, ".config", "vf"), nil
+}
+
+// SaveSession persists a session, writing the tokens to the OS keychain when
+// one is available and falling back to the 0600 session file otherwise.
+func SaveSession(s *Session) error {
+	if s == nil {
+		return errors.New("save session: nil session")
+	}
+
+	stored := *s
+	stored.Version = sessionVersion
+	stored.TokensInKeyring = writeSecrets(s.AccessToken, s.RefreshToken)
+	if stored.TokensInKeyring {
+		stored.AccessToken = ""
+		stored.RefreshToken = ""
+	}
+	// Report back where the secrets actually landed; callers render the
+	// storage location from the session they passed in.
+	s.Version = stored.Version
+	s.TokensInKeyring = stored.TokensInKeyring
+
+	return writeJSONFile(sessionFileName, &stored)
+}
+
+// writeSecrets stores the tokens in the OS keychain. It returns false when the
+// keychain is unavailable or rejects a value, in which case the caller keeps
+// the tokens in the session file instead.
+func writeSecrets(accessToken, refreshToken string) bool {
+	if !keyringAvailable() {
+		return false
+	}
+	if err := keyringSet(keyringAccessToken, accessToken); err != nil {
+		return false
+	}
+	if refreshToken == "" {
+		_ = keyringDelete(keyringRefreshToken)
+		return true
+	}
+	if err := keyringSet(keyringRefreshToken, refreshToken); err != nil {
+		// Roll back so a stale access token cannot outlive its refresh token.
+		_ = keyringDelete(keyringAccessToken)
+		return false
+	}
+	return true
+}
+
+// LoadSession reads the stored session, resolving tokens from the keychain
+// when that is where they were written. It returns ErrNoSession when nothing
+// is stored.
+func LoadSession() (*Session, error) {
+	var s Session
+	found, err := readJSONFile(sessionFileName, &s)
+	if err != nil {
+		return nil, err
+	}
+	if !found {
+		return nil, ErrNoSession
+	}
+
+	if s.TokensInKeyring {
+		s.AccessToken = keyringGet(keyringAccessToken)
+		s.RefreshToken = keyringGet(keyringRefreshToken)
+	}
+	if s.AccessToken == "" && s.RefreshToken == "" {
+		// The file survived but the keychain entries are gone (another
+		// machine's sync, a manual keychain purge, a different user).
+		return nil, ErrNoSession
+	}
+	return &s, nil
+}
+
+// ClearSession removes the stored session from both the keychain and disk. The
+// cached client registration is kept so the next login does not re-register.
+//
+// Every deletion is attempted, but a keychain failure is reported rather than
+// swallowed: dropping the session file while the keychain still holds usable
+// tokens would leave credentials behind with no record of where they are. The
+// file is kept in that case so a later logout can finish the job.
+func ClearSession() error {
+	var errs []error
+	if keyringAvailable() {
+		for _, key := range []string{keyringAccessToken, keyringRefreshToken} {
+			// A missing entry is the desired end state, not a failure.
+			if err := keyringDelete(key); err != nil && !errors.Is(err, keyring.ErrNotFound) {
+				errs = append(errs, fmt.Errorf("remove %s from the OS keychain: %w", key, err))
+			}
+		}
+	}
+	if len(errs) > 0 {
+		return errors.Join(errs...)
+	}
+	return removeFile(sessionFileName)
+}
+
+func loadClient(issuer string) (*clientRecord, error) {
+	var rec clientRecord
+	found, err := readJSONFile(clientFileName, &rec)
+	if err != nil || !found {
+		return nil, err
+	}
+	if rec.ClientID == "" || rec.Issuer != issuer {
+		return nil, nil
+	}
+	return &rec, nil
+}
+
+func saveClient(rec *clientRecord) error {
+	return writeJSONFile(clientFileName, rec)
+}
+
+func writeJSONFile(name string, value any) error {
+	dir, err := storeDir()
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		return fmt.Errorf("create %s: %w", dir, err)
+	}
+
+	data, err := json.MarshalIndent(value, "", "  ")
+	if err != nil {
+		return fmt.Errorf("encode %s: %w", name, err)
+	}
+	data = append(data, '\n')
+
+	// Write to a temp file in the same directory, then rename, so a crash
+	// mid-write cannot leave a half-written file behind.
+	path := filepath.Join(dir, name)
+	tmp, err := os.CreateTemp(dir, name+".*")
+	if err != nil {
+		return fmt.Errorf("create temp file in %s: %w", dir, err)
+	}
+	tmpPath := tmp.Name()
+	defer os.Remove(tmpPath) // no-op once the rename succeeds
+
+	// Owner-only permissions matter on Unix; Windows ignores the mode, which is
+	// acceptable there because the Credential Manager is the primary store.
+	_ = tmp.Chmod(0600)
+	if _, err := tmp.Write(data); err != nil {
+		tmp.Close()
+		return fmt.Errorf("write %s: %w", tmpPath, err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("close %s: %w", tmpPath, err)
+	}
+	if err := os.Rename(tmpPath, path); err != nil {
+		return fmt.Errorf("write %s: %w", path, err)
+	}
+	return nil
+}
+
+// readJSONFile decodes name into value. The bool reports whether the file
+// existed; a missing file is not an error.
+func readJSONFile(name string, value any) (bool, error) {
+	dir, err := storeDir()
+	if err != nil {
+		return false, err
+	}
+	path := filepath.Join(dir, name)
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return false, nil
+		}
+		return false, fmt.Errorf("read %s: %w", path, err)
+	}
+	if err := json.Unmarshal(data, value); err != nil {
+		return false, fmt.Errorf("parse %s: %w", path, err)
+	}
+	return true, nil
+}
+
+func removeFile(name string) error {
+	dir, err := storeDir()
+	if err != nil {
+		return err
+	}
+	path := filepath.Join(dir, name)
+	if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("remove %s: %w", path, err)
+	}
+	return nil
+}
+
+// storageLocation describes where the tokens for a session are kept, for
+// display in 'vf auth whoami'.
+func (s *Session) storageLocation() string {
+	if s.TokensInKeyring {
+		return "OS keychain"
+	}
+	dir, err := storeDir()
+	if err != nil {
+		return sessionFileName
+	}
+	return filepath.Join(dir, sessionFileName)
+}
diff --git a/internal/oauth/store_test.go b/internal/oauth/store_test.go
new file mode 100644
index 00000000..8debcb65
--- /dev/null
+++ b/internal/oauth/store_test.go
@@ -0,0 +1,254 @@
+package oauth
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/zalando/go-keyring"
+)
+
+func sampleSession() *Session {
+	return &Session{
+		Issuer:        DefaultIssuer,
+		TokenEndpoint: DefaultIssuer + "/v1alpha1/oauth2/token",
+		ClientID:      "client-123",
+		Resource:      DefaultResource,
+		Scope:         "universal.workspace.read",
+		TokenType:     "Bearer",
+		Expiry:        time.Now().Add(time.Hour).Truncate(time.Second),
+		ObtainedAt:    time.Now().Truncate(time.Second),
+		AccessToken:   "access-token-value",
+		RefreshToken:  "refresh-token-value",
+	}
+}
+
+func TestSaveSessionUsesKeychainWhenAvailable(t *testing.T) {
+	dir, ring := useTestStore(t, true)
+
+	if err := SaveSession(sampleSession()); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+
+	if got := ring.get(keyringAccessToken); got != "access-token-value" {
+		t.Errorf("keychain access token = %q, want the stored token", got)
+	}
+	if got := ring.get(keyringRefreshToken); got != "refresh-token-value" {
+		t.Errorf("keychain refresh token = %q, want the stored token", got)
+	}
+
+	raw, err := os.ReadFile(filepath.Join(dir, sessionFileName))
+	if err != nil {
+		t.Fatalf("read session file: %v", err)
+	}
+	if strings.Contains(string(raw), "access-token-value") || strings.Contains(string(raw), "refresh-token-value") {
+		t.Errorf("session file contains token material:\n%s", raw)
+	}
+
+	loaded, err := LoadSession()
+	if err != nil {
+		t.Fatalf("LoadSession: %v", err)
+	}
+	if loaded.AccessToken != "access-token-value" || loaded.RefreshToken != "refresh-token-value" {
+		t.Errorf("loaded tokens = %q/%q, want the stored pair", loaded.AccessToken, loaded.RefreshToken)
+	}
+	if loaded.ClientID != "client-123" || loaded.Scope != "universal.workspace.read" {
+		t.Errorf("loaded metadata = %+v, want the stored metadata", loaded)
+	}
+}
+
+func TestSaveSessionFallsBackToFileWithoutKeychain(t *testing.T) {
+	dir, _ := useTestStore(t, false)
+
+	if err := SaveSession(sampleSession()); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+
+	path := filepath.Join(dir, sessionFileName)
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read session file: %v", err)
+	}
+	if !strings.Contains(string(raw), "access-token-value") {
+		t.Errorf("session file is missing the fallback token:\n%s", raw)
+	}
+
+	if runtime.GOOS != "windows" {
+		info, err := os.Stat(path)
+		if err != nil {
+			t.Fatalf("stat session file: %v", err)
+		}
+		if mode := info.Mode().Perm(); mode != 0600 {
+			t.Errorf("session file mode = %o, want 600", mode)
+		}
+	}
+
+	loaded, err := LoadSession()
+	if err != nil {
+		t.Fatalf("LoadSession: %v", err)
+	}
+	if loaded.AccessToken != "access-token-value" {
+		t.Errorf("loaded access token = %q, want the fallback token", loaded.AccessToken)
+	}
+}
+
+func TestSaveSessionFallsBackWhenKeychainRejectsTheValue(t *testing.T) {
+	// The Windows Credential Manager rejects blobs over 2560 bytes; the store
+	// must keep working rather than losing the session.
+	dir, ring := useTestStore(t, true)
+	ring.setErr = errors.New("credential too large")
+
+	if err := SaveSession(sampleSession()); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+
+	raw, err := os.ReadFile(filepath.Join(dir, sessionFileName))
+	if err != nil {
+		t.Fatalf("read session file: %v", err)
+	}
+	if !strings.Contains(string(raw), "access-token-value") {
+		t.Errorf("session file is missing the fallback token:\n%s", raw)
+	}
+}
+
+func TestLoadSessionWithoutStoredSession(t *testing.T) {
+	useTestStore(t, true)
+
+	if _, err := LoadSession(); !errors.Is(err, ErrNoSession) {
+		t.Errorf("LoadSession error = %v, want ErrNoSession", err)
+	}
+}
+
+func TestLoadSessionWhenKeychainEntriesAreGone(t *testing.T) {
+	_, ring := useTestStore(t, true)
+
+	if err := SaveSession(sampleSession()); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+	// Simulate the keychain being cleared behind the CLI's back.
+	_ = ring.delete(keyringAccessToken)
+	_ = ring.delete(keyringRefreshToken)
+
+	if _, err := LoadSession(); !errors.Is(err, ErrNoSession) {
+		t.Errorf("LoadSession error = %v, want ErrNoSession", err)
+	}
+}
+
+func TestClearSessionRemovesTokensButKeepsClientRegistration(t *testing.T) {
+	dir, ring := useTestStore(t, true)
+
+	if err := SaveSession(sampleSession()); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+	if err := saveClient(&clientRecord{Issuer: DefaultIssuer, ClientID: "client-123", RedirectURIs: defaultRedirectURIs()}); err != nil {
+		t.Fatalf("saveClient: %v", err)
+	}
+
+	if err := ClearSession(); err != nil {
+		t.Fatalf("ClearSession: %v", err)
+	}
+
+	if ring.get(keyringAccessToken) != "" || ring.get(keyringRefreshToken) != "" {
+		t.Error("keychain still holds token material after ClearSession")
+	}
+	if _, err := os.Stat(filepath.Join(dir, sessionFileName)); !os.IsNotExist(err) {
+		t.Errorf("session file still present after ClearSession (err = %v)", err)
+	}
+
+	rec, err := loadClient(DefaultIssuer)
+	if err != nil {
+		t.Fatalf("loadClient: %v", err)
+	}
+	if rec == nil || rec.ClientID != "client-123" {
+		t.Error("client registration should survive logout so the next login can reuse it")
+	}
+}
+
+func TestClearSessionReportsAFailingKeychain(t *testing.T) {
+	// A locked keychain would otherwise leave usable tokens behind while
+	// logout removed the only record of where they are.
+	dir, ring := useTestStore(t, true)
+
+	if err := SaveSession(sampleSession()); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+	ring.deleteErr = errors.New("keychain is locked")
+
+	err := ClearSession()
+	if err == nil || !strings.Contains(err.Error(), "keychain is locked") {
+		t.Fatalf("ClearSession error = %v, want the keychain failure reported", err)
+	}
+	// Both entries are attempted, not just the first.
+	if got := strings.Count(err.Error(), "keychain is locked"); got != 2 {
+		t.Errorf("error mentions %d keychain failures, want both attempted:\n%v", got, err)
+	}
+	if _, statErr := os.Stat(filepath.Join(dir, sessionFileName)); statErr != nil {
+		t.Errorf("session file was removed despite the keychain failure (err = %v)", statErr)
+	}
+}
+
+func TestClearSessionToleratesMissingKeychainEntries(t *testing.T) {
+	dir, ring := useTestStore(t, true)
+
+	if err := SaveSession(sampleSession()); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+	// Nothing left to delete is the state logout is aiming for, not a failure.
+	ring.deleteErr = keyring.ErrNotFound
+
+	if err := ClearSession(); err != nil {
+		t.Fatalf("ClearSession: %v, want a missing entry treated as already gone", err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, sessionFileName)); !os.IsNotExist(err) {
+		t.Errorf("session file still present after ClearSession (err = %v)", err)
+	}
+}
+
+func TestSaveSessionReportsWhereTheTokensLanded(t *testing.T) {
+	// 'vf auth login' prints the storage location from the session it passed
+	// in, so SaveSession has to say where the secrets actually went.
+	useTestStore(t, true)
+
+	session := sampleSession()
+	if err := SaveSession(session); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+	if !session.TokensInKeyring {
+		t.Error("TokensInKeyring = false after a keychain-backed save")
+	}
+	if got := session.storageLocation(); got != "OS keychain" {
+		t.Errorf("storageLocation = %q, want the OS keychain", got)
+	}
+
+	fileBacked := sampleSession()
+	useTestStore(t, false)
+	if err := SaveSession(fileBacked); err != nil {
+		t.Fatalf("SaveSession: %v", err)
+	}
+	if fileBacked.TokensInKeyring {
+		t.Error("TokensInKeyring = true without a keychain")
+	}
+	if got := fileBacked.storageLocation(); !strings.HasSuffix(got, sessionFileName) {
+		t.Errorf("storageLocation = %q, want the session file", got)
+	}
+}
+
+func TestLoadClientIgnoresOtherIssuers(t *testing.T) {
+	useTestStore(t, true)
+
+	if err := saveClient(&clientRecord{Issuer: "https://staging.example.com", ClientID: "other"}); err != nil {
+		t.Fatalf("saveClient: %v", err)
+	}
+
+	rec, err := loadClient(DefaultIssuer)
+	if err != nil {
+		t.Fatalf("loadClient: %v", err)
+	}
+	if rec != nil {
+		t.Errorf("loadClient returned %+v for a different issuer, want nil", rec)
+	}
+}
diff --git a/internal/oauth/testsupport_test.go b/internal/oauth/testsupport_test.go
new file mode 100644
index 00000000..de371de8
--- /dev/null
+++ b/internal/oauth/testsupport_test.go
@@ -0,0 +1,82 @@
+package oauth
+
+import (
+	"net/http"
+	"sync"
+	"testing"
+	"time"
+)
+
+// fakeKeyring stands in for the OS keychain in tests.
+type fakeKeyring struct {
+	mu        sync.Mutex
+	values    map[string]string
+	available bool
+	setErr    error
+	deleteErr error
+}
+
+func newFakeKeyring(available bool) *fakeKeyring {
+	return &fakeKeyring{values: map[string]string{}, available: available}
+}
+
+func (f *fakeKeyring) get(key string) string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.values[key]
+}
+
+func (f *fakeKeyring) set(key, value string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.setErr != nil {
+		return f.setErr
+	}
+	f.values[key] = value
+	return nil
+}
+
+func (f *fakeKeyring) delete(key string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.deleteErr != nil {
+		return f.deleteErr
+	}
+	delete(f.values, key)
+	return nil
+}
+
+// useTestStore points the store at a temp directory and a fake keychain for
+// the duration of the test.
+func useTestStore(t *testing.T, available bool) (string, *fakeKeyring) {
+	t.Helper()
+
+	dir := t.TempDir()
+	ring := newFakeKeyring(available)
+
+	origDir, origAvailable, origGet, origSet, origDelete := storeDir, keyringAvailable, keyringGet, keyringSet, keyringDelete
+	storeDir = func() (string, error) { return dir, nil }
+	keyringAvailable = func() bool { return ring.available }
+	keyringGet = ring.get
+	keyringSet = ring.set
+	keyringDelete = ring.delete
+
+	t.Cleanup(func() {
+		storeDir, keyringAvailable, keyringGet, keyringSet, keyringDelete = origDir, origAvailable, origGet, origSet, origDelete
+	})
+	return dir, ring
+}
+
+// useTestHTTPClient swaps in a client with a short timeout so a hung test
+// server fails fast.
+func useTestHTTPClient(t *testing.T) {
+	t.Helper()
+	orig := httpClient
+	httpClient = &http.Client{Timeout: 10 * time.Second}
+	t.Cleanup(func() { httpClient = orig })
+}
+
+// envFunc builds a getenv replacement backed by a map.
+func envFunc(values map[string]string) func(string) string {
+	return func(key string) string { return values[key] }
+}
diff --git a/internal/oauth/token.go b/internal/oauth/token.go
new file mode 100644
index 00000000..9e9d63c3
--- /dev/null
+++ b/internal/oauth/token.go
@@ -0,0 +1,134 @@
+package oauth
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// tokenResponse is the RFC 6749 token endpoint success response.
+type tokenResponse struct {
+	AccessToken  string `json:"access_token"`
+	TokenType    string `json:"token_type"`
+	ExpiresIn    int64  `json:"expires_in"`
+	RefreshToken string `json:"refresh_token"`
+	Scope        string `json:"scope"`
+}
+
+// tokenError is the RFC 6749 token endpoint error response. The authorization
+// server also returns generic {message, statusCode} envelopes for some
+// failures, so both shapes are decoded.
+type tokenError struct {
+	Code        string `json:"error"`
+	Description string `json:"error_description"`
+	Message     string `json:"message"`
+	StatusCode  int    `json:"statusCode"`
+}
+
+func (e *tokenError) Error() string {
+	switch {
+	case e.Code != "" && e.Description != "":
+		return fmt.Sprintf("%s: %s", e.Code, e.Description)
+	case e.Code != "":
+		return e.Code
+	case e.Message != "":
+		return e.Message
+	default:
+		return "token request failed"
+	}
+}
+
+// isInvalidGrant reports whether the server rejected the refresh token, which
+// means the session is finished and the user has to log in again.
+func (e *tokenError) isInvalidGrant() bool {
+	return e.Code == "invalid_grant" || e.StatusCode == http.StatusUnauthorized
+}
+
+// exchangeCode trades an authorization code for tokens (RFC 6749 §4.1.3) with
+// the PKCE verifier and the RFC 8707 resource indicator.
+func exchangeCode(ctx context.Context, hc *http.Client, md Metadata, clientID, code, verifier, redirectURI, resource string) (*tokenResponse, error) {
+	form := url.Values{
+		"grant_type":    {"authorization_code"},
+		"code":          {code},
+		"redirect_uri":  {redirectURI},
+		"client_id":     {clientID},
+		"code_verifier": {verifier},
+	}
+	if resource != "" {
+		form.Set("resource", resource)
+	}
+	return postToken(ctx, hc, md.TokenEndpoint, form)
+}
+
+// refreshTokens exchanges a refresh token for a fresh access token
+// (RFC 6749 §6).
+func refreshTokens(ctx context.Context, hc *http.Client, tokenEndpoint, clientID, refreshToken, scope, resource string) (*tokenResponse, error) {
+	form := url.Values{
+		"grant_type":    {"refresh_token"},
+		"refresh_token": {refreshToken},
+		"client_id":     {clientID},
+	}
+	if scope != "" {
+		form.Set("scope", scope)
+	}
+	if resource != "" {
+		form.Set("resource", resource)
+	}
+	return postToken(ctx, hc, tokenEndpoint, form)
+}
+
+func postToken(ctx context.Context, hc *http.Client, endpoint string, form url.Values) (*tokenResponse, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, strings.NewReader(form.Encode()))
+	if err != nil {
+		return nil, fmt.Errorf("build token request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := hc.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("call token endpoint: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, fmt.Errorf("read token response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		tokErr := &tokenError{StatusCode: resp.StatusCode}
+		if err := json.Unmarshal(body, tokErr); err != nil || (tokErr.Code == "" && tokErr.Message == "") {
+			return nil, fmt.Errorf("token endpoint returned %s", resp.Status)
+		}
+		if tokErr.StatusCode == 0 {
+			tokErr.StatusCode = resp.StatusCode
+		}
+		return nil, tokErr
+	}
+
+	var tok tokenResponse
+	if err := json.Unmarshal(body, &tok); err != nil {
+		return nil, fmt.Errorf("parse token response: %w", err)
+	}
+	if tok.AccessToken == "" {
+		return nil, fmt.Errorf("token endpoint returned no access token")
+	}
+	return &tok, nil
+}
+
+// expiry converts the response's relative lifetime into an absolute time.
+// A response without expires_in yields the zero time, which is treated as
+// "unknown lifetime": the token is refreshed on assumedTokenLifetime instead.
+// See Session.needsRefresh.
+func (t *tokenResponse) expiry(now time.Time) time.Time {
+	if t.ExpiresIn <= 0 {
+		return time.Time{}
+	}
+	return now.Add(time.Duration(t.ExpiresIn) * time.Second)
+}
diff --git a/internal/oauth/token_test.go b/internal/oauth/token_test.go
new file mode 100644
index 00000000..1a4f6bde
--- /dev/null
+++ b/internal/oauth/token_test.go
@@ -0,0 +1,109 @@
+package oauth
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+	"time"
+)
+
+func TestExchangeCodeSendsPKCEAndResource(t *testing.T) {
+	var form url.Values
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := r.ParseForm(); err != nil {
+			t.Errorf("parse form: %v", err)
+		}
+		form = r.PostForm
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"access_token":"at","refresh_token":"rt","token_type":"Bearer","expires_in":3600,"scope":"universal.workspace.read"}`))
+	}))
+	defer server.Close()
+
+	md := Metadata{TokenEndpoint: server.URL}
+	tok, err := exchangeCode(context.Background(), server.Client(), md, "client-1", "the-code", "the-verifier", "http://127.0.0.1:51330/oauth/callback", DefaultResource)
+	if err != nil {
+		t.Fatalf("exchangeCode: %v", err)
+	}
+
+	want := map[string]string{
+		"grant_type":    "authorization_code",
+		"code":          "the-code",
+		"client_id":     "client-1",
+		"code_verifier": "the-verifier",
+		"redirect_uri":  "http://127.0.0.1:51330/oauth/callback",
+		"resource":      DefaultResource,
+	}
+	for key, value := range want {
+		if got := form.Get(key); got != value {
+			t.Errorf("form[%s] = %q, want %q", key, got, value)
+		}
+	}
+
+	if tok.AccessToken != "at" || tok.RefreshToken != "rt" {
+		t.Errorf("tokens = %q/%q, want at/rt", tok.AccessToken, tok.RefreshToken)
+	}
+	now := time.Now()
+	if got := tok.expiry(now); got.Sub(now) != time.Hour {
+		t.Errorf("expiry = %v, want one hour out", got)
+	}
+}
+
+func TestExpiryIsZeroWithoutExpiresIn(t *testing.T) {
+	tok := &tokenResponse{AccessToken: "at"}
+	if got := tok.expiry(time.Now()); !got.IsZero() {
+		t.Errorf("expiry = %v, want the zero time when the server states no lifetime", got)
+	}
+}
+
+func TestRefreshTokensReportsInvalidGrant(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		w.Write([]byte(`{"error":"invalid_grant","error_description":"refresh token expired"}`))
+	}))
+	defer server.Close()
+
+	_, err := refreshTokens(context.Background(), server.Client(), server.URL, "client-1", "rt", "", "")
+	var tokErr *tokenError
+	if !errors.As(err, &tokErr) {
+		t.Fatalf("error = %v, want a *tokenError", err)
+	}
+	if !tokErr.isInvalidGrant() {
+		t.Errorf("isInvalidGrant() = false for %v", tokErr)
+	}
+	if tokErr.Error() != "invalid_grant: refresh token expired" {
+		t.Errorf("message = %q, want the server's description", tokErr.Error())
+	}
+}
+
+func TestPostTokenTreatsUnauthorizedAsInvalidGrant(t *testing.T) {
+	// The Voiceflow token endpoint answers a bad code with a bare 401 envelope
+	// rather than an RFC 6749 error body.
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusUnauthorized)
+		w.Write([]byte(`{"message":"Unauthorized","statusCode":401}`))
+	}))
+	defer server.Close()
+
+	_, err := refreshTokens(context.Background(), server.Client(), server.URL, "client-1", "rt", "", "")
+	var tokErr *tokenError
+	if !errors.As(err, &tokErr) || !tokErr.isInvalidGrant() {
+		t.Fatalf("error = %v, want an invalid-grant *tokenError", err)
+	}
+}
+
+func TestPostTokenRejectsResponseWithoutAccessToken(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"token_type":"Bearer"}`))
+	}))
+	defer server.Close()
+
+	if _, err := refreshTokens(context.Background(), server.Client(), server.URL, "client-1", "rt", "", ""); err == nil {
+		t.Fatal("expected an error when the response carries no access token")
+	}
+}