diff --git a/standard/cli/command-reference/porter-auth.mdx b/standard/cli/command-reference/porter-auth.mdx
index 97f12f8..9ebc710 100644
--- a/standard/cli/command-reference/porter-auth.mdx
+++ b/standard/cli/command-reference/porter-auth.mdx
@@ -36,6 +36,21 @@ porter auth login --token <YOUR_TOKEN>
 After logging in, Porter automatically sets your default project and cluster if you have access to any. You can view these with `porter config`.
 </Info>
 
+### Login methods
+
+`porter auth login` supports two browser-based flows. Switch between them with [`porter config set-login-method`](/standard/cli/command-reference/porter-config#porter-config-set-login-method).
+
+| Method | Credential stored locally | Token lifetime |
+|--------|---------------------------|----------------|
+| `v1` (default) | Long-lived Porter JWT | Does not expire |
+| `v2` | Short-lived WorkOS access token issued via PKCE | Refreshed automatically; expires after a short window |
+
+The `v2` flow signs in through your Porter SSO identity provider and authenticates subsequent API requests with a short-lived access token. Use it when your organization requires session-bound credentials on developer machines. The `v1` flow remains the default and is recommended for CI/CD and other automated environments that need a stable long-lived token.
+
+<Info>
+Both flows use the same `porter auth login` command — only the credential stored in `~/.porter/config.json` and sent on each request differs. No changes are required to existing scripts when staying on `v1`.
+</Info>
+
 ---
 
 ## `porter auth logout`
diff --git a/standard/cli/command-reference/porter-config.mdx b/standard/cli/command-reference/porter-config.mdx
index 2c15123..e230c28 100644
--- a/standard/cli/command-reference/porter-config.mdx
+++ b/standard/cli/command-reference/porter-config.mdx
@@ -45,6 +45,34 @@ porter config set-project 12345
 
 ---
 
+## `porter config set-login-method`
+
+Select which browser-based login flow `porter auth login` uses.
+
+**Usage:**
+<CodeGroup>
+```bash Use v2 (WorkOS PKCE, short-lived tokens)
+porter config set-login-method v2
+```
+
+```bash Use v1 (Porter JWT, long-lived token)
+porter config set-login-method v1
+```
+</CodeGroup>
+
+| Method | When to use |
+|--------|-------------|
+| `v1` (default) | CI/CD pipelines, scripts, and any environment that needs a long-lived token. |
+| `v2` | Developer machines where your organization requires session-bound credentials. Signs in through Porter SSO and stores a short-lived WorkOS access token that is refreshed automatically. |
+
+After switching, run `porter auth login` again to reauthenticate with the selected method.
+
+<Info>
+The `v2` flow is supported on Porter API hosts that have WorkOS configured. If your instance does not have WorkOS enabled, stay on `v1`.
+</Info>
+
+---
+
 ## `porter config set-cluster`
 
 Set the active cluster. This command shows a list of clusters in the current project and lets you select one.