fix(auth): fall back to OAuth when env token lacks endpoint permissions (#673)

## Summary

Fixes #646

When `SENTRY_AUTH_TOKEN` is set by build tooling (e.g., the Sentry
wizard's `.env.sentry-build-plugin`) but lacks the scopes needed for
interactive CLI commands, the CLI now prefers stored OAuth credentials
by default.

### OAuth-preferred default

When the user is logged in via OAuth, env tokens are automatically
skipped — `getEnvToken()` returns `undefined` when
`hasStoredAuthCredentials()` is true, cascading through all consumers
(`isEnvTokenActive`, `refreshToken`, `handleUnauthorized`, etc.). Set
`SENTRY_FORCE_ENV_TOKEN=1` to restore the old env-token-first priority.

### Other improvements

- **Login unblocked**: `sentry auth login` no longer blocks when an env
token is present — warns and proceeds to store OAuth credentials
separately.
- **Auth status enriched**: `sentry auth status` shows env token info
(whether it's active or bypassed in favor of OAuth).
- **Enhanced error messages** when env token is the only auth source and
it fails (401 converts to `AuthError` triggering auto-login; 403 adds
guidance).

Author: BYK

src/commands/auth/login.ts

@@ -9,6 +9,7 @@ import { buildCommand, numberParser } from "../../lib/command.js";
 import {
   clearAuth,
   getActiveEnvVarName,
+  hasStoredAuthCredentials,
   isAuthenticated,
   isEnvTokenActive,
   setAuthToken,
@@ -71,11 +72,15 @@ type LoginFlags = {
 async function handleExistingAuth(force: boolean): Promise<boolean> {
   if (isEnvTokenActive()) {
     const envVar = getActiveEnvVarName();
-    log.info(
-      `Authentication is provided via ${envVar} environment variable. ` +
-        `Unset ${envVar} to use OAuth-based login instead.`
+    log.warn(
+      `${envVar} is set in your environment (likely from build tooling).\n` +
+        "  OAuth credentials will be stored separately and used for CLI commands."
     );
-    return false;
+    // If no stored OAuth token exists, proceed directly to login
+    if (!hasStoredAuthCredentials()) {
+      return true;
+    }
+    // Fall through to the re-auth confirmation logic below
   }
 
   if (!force) {

src/commands/auth/logout.ts

@@ -8,9 +8,10 @@ import type { SentryContext } from "../../context.js";
 import { buildCommand } from "../../lib/command.js";
 import {
   clearAuth,
+  ENV_SOURCE_PREFIX,
   getActiveEnvVarName,
+  getAuthConfig,
   isAuthenticated,
-  isEnvTokenActive,
 } from "../../lib/db/auth.js";
 import { getDbPath } from "../../lib/db/index.js";
 import { AuthError } from "../../lib/errors.js";
@@ -46,7 +47,8 @@ export const logoutCommand = buildCommand({
       });
     }
 
-    if (isEnvTokenActive()) {
+    const auth = getAuthConfig();
+    if (auth?.source.startsWith(ENV_SOURCE_PREFIX)) {
       const envVar = getActiveEnvVarName();
       throw new AuthError(
         "invalid",

src/commands/auth/refresh.ts

@@ -7,9 +7,9 @@
 import type { SentryContext } from "../../context.js";
 import { buildCommand } from "../../lib/command.js";
 import {
+  ENV_SOURCE_PREFIX,
   getActiveEnvVarName,
   getAuthConfig,
-  isEnvTokenActive,
   refreshToken,
 } from "../../lib/db/auth.js";
 import { AuthError } from "../../lib/errors.js";
@@ -71,8 +71,9 @@ Examples:
     },
   },
   async *func(this: SentryContext, flags: RefreshFlags) {
-    // Env var tokens can't be refreshed
-    if (isEnvTokenActive()) {
+    // Env var tokens can't be refreshed — only block if env is the effective source
+    const currentAuth = getAuthConfig();
+    if (currentAuth?.source.startsWith(ENV_SOURCE_PREFIX)) {
       const envVar = getActiveEnvVarName();
       throw new AuthError(
         "invalid",

src/commands/auth/status.ts

@@ -11,7 +11,9 @@ import {
   type AuthConfig,
   type AuthSource,
   ENV_SOURCE_PREFIX,
+  getActiveEnvVarName,
   getAuthConfig,
+  getRawEnvToken,
   isAuthenticated,
 } from "../../lib/db/auth.js";
 import {
@@ -77,6 +79,13 @@ export type AuthStatusData = {
     /** Error message if verification failed */
     error?: string;
   };
+  /** Environment variable token info (present when SENTRY_AUTH_TOKEN or SENTRY_TOKEN is set) */
+  envToken?: {
+    /** Name of the env var (e.g., "SENTRY_AUTH_TOKEN") */
+    envVar: string;
+    /** Whether the env token is the effective auth source (vs bypassed for OAuth) */
+    active: boolean;
+  };
 };
 
 /**
@@ -186,6 +195,13 @@ export const statusCommand = buildCommand({
         : undefined;
     }
 
+    // Check for env token regardless of whether it's the active source
+    // (it may be set but bypassed because stored OAuth takes priority)
+    const rawEnv = getRawEnvToken();
+    const envTokenData: AuthStatusData["envToken"] = rawEnv
+      ? { envVar: getActiveEnvVarName(), active: fromEnv }
+      : undefined;
+
     const data: AuthStatusData = {
       authenticated: true,
       source: auth?.source ?? "oauth",
@@ -194,6 +210,7 @@ export const statusCommand = buildCommand({
       token: collectTokenInfo(auth, flags["show-token"]),
       defaults: collectDefaults(),
       verification: await verifyCredentials(),
+      envToken: envTokenData,
     };
 
     yield new CommandOutput(data);

src/lib/api/infrastructure.ts

@@ -57,6 +57,7 @@ export function throwApiError(
     error && typeof error === "object" && "detail" in error
       ? stringifyUnknown((error as { detail: unknown }).detail)
       : stringifyUnknown(error);
+
   throw new ApiError(
     `${context}: ${status} ${response.statusText ?? "Unknown"}`,
     status,

src/lib/db/auth.ts

@@ -36,10 +36,34 @@ export type AuthConfig = {
   source: AuthSource;
 };
 
+/**
+ * Read the raw token string from environment variables, ignoring all filters.
+ *
+ * Unlike {@link getEnvToken}, this always returns the env token if set, even
+ * when stored OAuth credentials would normally take priority. Used by the HTTP
+ * layer to check "was an env token provided?" independent of whether it's being
+ * used, and by the per-endpoint permission cache.
+ */
+export function getRawEnvToken(): string | undefined {
+  const authToken = getEnv().SENTRY_AUTH_TOKEN?.trim();
+  if (authToken) {
+    return authToken;
+  }
+  const sentryToken = getEnv().SENTRY_TOKEN?.trim();
+  if (sentryToken) {
+    return sentryToken;
+  }
+  return;
+}
+
 /**
  * Read token from environment variables.
  * `SENTRY_AUTH_TOKEN` takes priority over `SENTRY_TOKEN` (matches legacy sentry-cli).
  * Empty or whitespace-only values are treated as unset.
+ *
+ * This function is intentionally pure (no DB access). The "prefer stored OAuth
+ * over env token" logic lives in {@link getAuthToken} and {@link getAuthConfig}
+ * which check the DB first when `SENTRY_FORCE_ENV_TOKEN` is not set.
  */
 function getEnvToken(): { token: string; source: AuthSource } | undefined {
   const authToken = getEnv().SENTRY_AUTH_TOKEN?.trim();
@@ -62,28 +86,36 @@ export function isEnvTokenActive(): boolean {
 }
 
 /**
- * Get the name of the active env var providing authentication.
- * Returns the specific variable name (e.g. "SENTRY_AUTH_TOKEN" or "SENTRY_TOKEN").
- *
- * **Important**: Call only after checking {@link isEnvTokenActive} returns true.
- * Falls back to "SENTRY_AUTH_TOKEN" if no env source is active, which is a safe
- * default for error messages but may be misleading if used unconditionally.
+ * Get the name of the env var providing a token, for error messages.
+ * Returns the specific variable name (e.g. "SENTRY_AUTH_TOKEN" or "SENTRY_TOKEN")
+ * by checking which env var {@link getRawEnvToken} would read.
+ * Falls back to "SENTRY_AUTH_TOKEN" if no env var is set.
  */
 export function getActiveEnvVarName(): string {
-  const env = getEnvToken();
-  if (env) {
-    return env.source.slice(ENV_SOURCE_PREFIX.length);
+  // Match getRawEnvToken() priority: SENTRY_AUTH_TOKEN first, then SENTRY_TOKEN
+  if (getEnv().SENTRY_AUTH_TOKEN?.trim()) {
+    return "SENTRY_AUTH_TOKEN";
+  }
+  if (getEnv().SENTRY_TOKEN?.trim()) {
+    return "SENTRY_TOKEN";
   }
   return "SENTRY_AUTH_TOKEN";
 }
 
 export function getAuthConfig(): AuthConfig | undefined {
-  const envToken = getEnvToken();
-  if (envToken) {
-    return { token: envToken.token, source: envToken.source };
+  // When SENTRY_FORCE_ENV_TOKEN is set, check env first (old behavior).
+  // Otherwise, check the DB first — stored OAuth takes priority over env tokens.
+  // This is the core fix for #646: wizard-generated build tokens no longer
+  // silently override the user's interactive login.
+  const forceEnv = getEnv().SENTRY_FORCE_ENV_TOKEN?.trim();
+  if (forceEnv) {
+    const envToken = getEnvToken();
+    if (envToken) {
+      return { token: envToken.token, source: envToken.source };
+    }
   }
 
-  return withDbSpan("getAuthConfig", () => {
+  const dbConfig = withDbSpan("getAuthConfig", () => {
     const db = getDatabase();
     const row = db.query("SELECT * FROM auth WHERE id = 1").get() as
       | AuthRow
@@ -93,6 +125,13 @@ export function getAuthConfig(): AuthConfig | undefined {
       return;
     }
 
+    // Skip expired tokens without a refresh token — they're unusable.
+    // Expired tokens WITH a refresh token are kept: auth refresh and
+    // refreshToken() need them to perform the OAuth refresh flow.
+    if (row.expires_at && Date.now() > row.expires_at && !row.refresh_token) {
+      return;
+    }
+
     return {
       token: row.token ?? undefined,
       refreshToken: row.refresh_token ?? undefined,
@@ -101,16 +140,34 @@ export function getAuthConfig(): AuthConfig | undefined {
       source: "oauth" as const,
     };
   });
-}
+  if (dbConfig) {
+    return dbConfig;
+  }
 
-/** Get the active auth token. Checks env vars first, then falls back to SQLite. */
-export function getAuthToken(): string | undefined {
+  // No stored OAuth — fall back to env token
   const envToken = getEnvToken();
   if (envToken) {
-    return envToken.token;
+    return { token: envToken.token, source: envToken.source };
   }
+  return;
+}
 
-  return withDbSpan("getAuthToken", () => {
+/**
+ * Get the active auth token.
+ *
+ * Default: checks the DB first (stored OAuth wins), then falls back to env vars.
+ * With `SENTRY_FORCE_ENV_TOKEN=1`: checks env vars first (old behavior).
+ */
+export function getAuthToken(): string | undefined {
+  const forceEnv = getEnv().SENTRY_FORCE_ENV_TOKEN?.trim();
+  if (forceEnv) {
+    const envToken = getEnvToken();
+    if (envToken) {
+      return envToken.token;
+    }
+  }
+
+  const dbToken = withDbSpan("getAuthToken", () => {
     const db = getDatabase();
     const row = db.query("SELECT * FROM auth WHERE id = 1").get() as
       | AuthRow
@@ -126,6 +183,16 @@ export function getAuthToken(): string | undefined {
 
     return row.token;
   });
+  if (dbToken) {
+    return dbToken;
+  }
+
+  // No stored OAuth — fall back to env token
+  const envToken = getEnvToken();
+  if (envToken) {
+    return envToken.token;
+  }
+  return;
 }
 
 export function setAuthToken(
@@ -179,6 +246,32 @@ export function isAuthenticated(): boolean {
   return !!token;
 }
 
+/**
+ * Check if usable OAuth credentials are stored in the database.
+ *
+ * Returns true when the `auth` table has either:
+ * - A non-expired token, or
+ * - An expired token with a refresh token (will be refreshed on next use)
+ *
+ * Used by the login command to decide whether to prompt for re-authentication
+ * when an env token is present.
+ */
+export function hasStoredAuthCredentials(): boolean {
+  const db = getDatabase();
+  const row = db.query("SELECT * FROM auth WHERE id = 1").get() as
+    | AuthRow
+    | undefined;
+  if (!row?.token) {
+    return false;
+  }
+  // Non-expired token
+  if (!row.expires_at || Date.now() <= row.expires_at) {
+    return true;
+  }
+  // Expired but has refresh token — will be refreshed on next use
+  return !!row.refresh_token;
+}
+
 export type RefreshTokenOptions = {
   /** Bypass threshold check and always refresh */
   force?: boolean;
@@ -229,10 +322,13 @@ async function performTokenRefresh(
 export async function refreshToken(
   options: RefreshTokenOptions = {}
 ): Promise<RefreshTokenResult> {
-  // Env var tokens are assumed valid — no refresh, no expiry check
-  const envToken = getEnvToken();
-  if (envToken) {
-    return { token: envToken.token, refreshed: false };
+  // With SENTRY_FORCE_ENV_TOKEN, env token takes priority (no refresh needed).
+  const forceEnv = getEnv().SENTRY_FORCE_ENV_TOKEN?.trim();
+  if (forceEnv) {
+    const envToken = getEnvToken();
+    if (envToken) {
+      return { token: envToken.token, refreshed: false };
+    }
   }
 
   const { force = false } = options;
@@ -244,6 +340,11 @@ export async function refreshToken(
     | undefined;
 
   if (!row?.token) {
+    // No stored token — try env token as fallback
+    const envToken = getEnvToken();
+    if (envToken) {
+      return { token: envToken.token, refreshed: false };
+    }
     throw new AuthError("not_authenticated");
   }
 
@@ -271,6 +372,11 @@ export async function refreshToken(
 
   if (!row.refresh_token) {
     await clearAuth();
+    // Fall back to env token if available (consistent with getAuthToken/getAuthConfig)
+    const envToken = getEnvToken();
+    if (envToken) {
+      return { token: envToken.token, refreshed: false };
+    }
     throw new AuthError(
       "expired",
       "Session expired and no refresh token available. Run 'sentry auth login'."

src/lib/formatters/human.ts

@@ -1826,6 +1826,10 @@ export function formatAuthStatus(data: AuthStatusData): string {
     lines.push(mdKvTable(authRows));
   }
 
+  if (data.envToken) {
+    lines.push(formatEnvTokenSection(data.envToken));
+  }
+
   if (data.defaults) {
     lines.push(formatDefaultsSection(data.defaults));
   }
@@ -1837,6 +1841,24 @@ export function formatAuthStatus(data: AuthStatusData): string {
   return renderMarkdown(lines.join("\n"));
 }
 
+/**
+ * Format the env token status section.
+ * Shows whether the env token is active or bypassed, and how many endpoints
+ * have been marked insufficient.
+ */
+function formatEnvTokenSection(
+  envToken: NonNullable<AuthStatusData["envToken"]>
+): string {
+  const status = envToken.active
+    ? "active"
+    : "set but not used (using OAuth credentials)";
+  const rows: [string, string][] = [
+    ["Env var", safeCodeSpan(envToken.envVar)],
+    ["Status", status],
+  ];
+  return `\n${mdKvTable(rows, "Environment Token")}`;
+}
+
 // Project Creation Formatting
 
 /** Input for the project-created success formatter */