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

When SENTRY_AUTH_TOKEN is set by build tooling (e.g. the Sentry wizard)
but lacks the scopes needed for interactive CLI commands, the CLI now
automatically falls back to stored OAuth credentials instead of failing
with confusing 401/403 errors.

Per-endpoint permission cache: when an env token gets a 401/403 on a
specific endpoint, the (token, method, url_path) tuple is stored in a
new env_token_permissions table. Subsequent requests to that endpoint
skip the env token and use OAuth directly — zero wasted API calls.

Key changes:
- New env_token_permissions table (schema v13) with 24h TTL and lazy
  probabilistic cleanup via the existing cleanupExpiredCaches path
- HTTP layer pre-checks the cache before each request; on cache miss
  with 401/403, marks the endpoint, retries with OAuth, logs a warning
- sentry auth login no longer blocks when an env token is present —
  warns and proceeds to store OAuth credentials separately
- sentry auth status shows env token info (active, bypassed endpoints)
- SENTRY_IGNORE_ENV_TOKEN env var as escape hatch to skip env tokens
- --fresh clears the permission cache for re-evaluation
- Enhanced 401/403 error messages when no OAuth fallback is available

Author: BYK

src/commands/auth/login.ts

@@ -9,6 +9,7 @@ import { buildCommand, numberParser } from "../../lib/command.js";
 import {
   clearAuth,
   getActiveEnvVarName,
+  hasStoredAuthToken,
   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 (!hasStoredAuthToken()) {
+      return true;
+    }
+    // Fall through to the re-auth confirmation logic below
   }
 
   if (!force) {

src/commands/auth/status.ts

@@ -11,13 +11,17 @@ import {
   type AuthConfig,
   type AuthSource,
   ENV_SOURCE_PREFIX,
+  getActiveEnvVarName,
   getAuthConfig,
+  getRawEnvToken,
   isAuthenticated,
+  isEnvTokenActive,
 } from "../../lib/db/auth.js";
 import {
   getDefaultOrganization,
   getDefaultProject,
 } from "../../lib/db/defaults.js";
+import { countInsufficientEndpoints } from "../../lib/db/env-token-cache.js";
 import { getDbPath } from "../../lib/db/index.js";
 import { getUserInfo } from "../../lib/db/user.js";
 import { AuthError, stringifyUnknown } from "../../lib/errors.js";
@@ -77,6 +81,15 @@ 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;
+    /** Number of endpoints where this token has been found insufficient */
+    insufficientEndpoints: number;
+  };
 };
 
 /**
@@ -186,6 +199,24 @@ export const statusCommand = buildCommand({
         : undefined;
     }
 
+    // Check for env token regardless of whether it's the active source
+    // (it may be set but bypassed due to insufficient permissions)
+    const rawEnv = getRawEnvToken();
+    let envTokenData: AuthStatusData["envToken"];
+    if (rawEnv) {
+      let insufficientCount = 0;
+      try {
+        insufficientCount = countInsufficientEndpoints(rawEnv);
+      } catch {
+        // Non-fatal: DB may be unavailable in some test/CI environments
+      }
+      envTokenData = {
+        envVar: getActiveEnvVarName(),
+        active: isEnvTokenActive(),
+        insufficientEndpoints: insufficientCount,
+      };
+    }
+
     const data: AuthStatusData = {
       authenticated: true,
       source: auth?.source ?? "oauth",
@@ -194,6 +225,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

@@ -10,6 +10,7 @@
 import * as Sentry from "@sentry/node-core/light";
 import type { z } from "zod";
 
+import { getRawEnvToken } from "../db/auth.js";
 import { getEnv } from "../env.js";
 import { ApiError, AuthError, stringifyUnknown } from "../errors.js";
 import { resolveOrgRegion } from "../region.js";
@@ -57,6 +58,29 @@ export function throwApiError(
     error && typeof error === "object" && "detail" in error
       ? stringifyUnknown((error as { detail: unknown }).detail)
       : stringifyUnknown(error);
+
+  // When an env token is set and we get 401, the HTTP-layer fallback to
+  // stored OAuth already failed (no stored credentials). Convert to AuthError
+  // so the auto-login middleware in cli.ts can trigger interactive login.
+  if (status === 401 && getRawEnvToken()) {
+    throw new AuthError(
+      "not_authenticated",
+      `${context}: ${status} ${response.statusText ?? "Unknown"}.\n` +
+        "  SENTRY_AUTH_TOKEN is set but lacks permissions for this endpoint.\n" +
+        "  Run 'sentry auth login' to authenticate with OAuth, or set SENTRY_IGNORE_ENV_TOKEN=1."
+    );
+  }
+
+  // For 403 with env token, keep as ApiError but add guidance
+  if (status === 403 && getRawEnvToken()) {
+    throw new ApiError(
+      `${context}: ${status} ${response.statusText ?? "Unknown"}`,
+      status,
+      `${detail}\n\n  SENTRY_AUTH_TOKEN may lack permissions for this endpoint.\n` +
+        "  Run 'sentry auth login' to authenticate with OAuth, or set SENTRY_IGNORE_ENV_TOKEN=1."
+    );
+  }
+
   throw new ApiError(
     `${context}: ${status} ${response.statusText ?? "Unknown"}`,
     status,

src/lib/db/auth.ts

@@ -5,6 +5,7 @@
 import { getEnv } from "../env.js";
 import { clearResponseCache } from "../response-cache.js";
 import { withDbSpan } from "../telemetry.js";
+import { clearEnvTokenCache } from "./env-token-cache.js";
 import { getDatabase } from "./index.js";
 import { runUpsert } from "./utils.js";
 
@@ -36,12 +37,38 @@ 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 `SENTRY_IGNORE_ENV_TOKEN` is active. Used by the HTTP layer to check
+ * "was an env token provided?" independent of whether it's being used.
+ */
+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.
+ *
+ * Returns `undefined` when `SENTRY_IGNORE_ENV_TOKEN` is set, causing all
+ * downstream consumers to fall through to stored OAuth credentials.
  */
 function getEnvToken(): { token: string; source: AuthSource } | undefined {
+  if (getEnv().SENTRY_IGNORE_ENV_TOKEN?.trim()) {
+    return;
+  }
+
   const authToken = getEnv().SENTRY_AUTH_TOKEN?.trim();
   if (authToken) {
     return { token: authToken, source: "env:SENTRY_AUTH_TOKEN" };
@@ -165,6 +192,9 @@ export async function clearAuth(): Promise<void> {
     db.query("DELETE FROM pagination_cursors").run();
   });
 
+  // Clear env token permission cache — stale marks are meaningless after logout
+  clearEnvTokenCache();
+
   // Clear cached API responses — they are tied to the current user's permissions.
   // Awaited so cache is fully removed before the process exits.
   try {
@@ -179,9 +209,38 @@ export function isAuthenticated(): boolean {
   return !!token;
 }
 
+/**
+ * Check if a valid OAuth token is stored in the database.
+ *
+ * Returns true if the `auth` table has a non-expired token, regardless of
+ * whether an env token is active. Used by the login command to decide whether
+ * to prompt for re-authentication when an env token is present.
+ */
+export function hasStoredAuthToken(): boolean {
+  return withDbSpan("hasStoredAuthToken", () => {
+    const db = getDatabase();
+    const row = db.query("SELECT * FROM auth WHERE id = 1").get() as
+      | AuthRow
+      | undefined;
+    if (!row?.token) {
+      return false;
+    }
+    if (row.expires_at && Date.now() > row.expires_at) {
+      return false;
+    }
+    return true;
+  });
+}
+
 export type RefreshTokenOptions = {
   /** Bypass threshold check and always refresh */
   force?: boolean;
+  /**
+   * Skip the env token and go directly to stored OAuth credentials.
+   * Used by the HTTP fallback layer when the env token is known-insufficient
+   * for a specific endpoint.
+   */
+  skipEnv?: boolean;
 };
 
 export type RefreshTokenResult = {
@@ -229,10 +288,14 @@ 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 };
+  // Env var tokens are assumed valid — no refresh, no expiry check.
+  // skipEnv bypasses this for the OAuth fallback path when the env token
+  // is known-insufficient for a specific endpoint.
+  if (!options.skipEnv) {
+    const envToken = getEnvToken();
+    if (envToken) {
+      return { token: envToken.token, refreshed: false };
+    }
   }
 
   const { force = false } = options;

src/lib/db/env-token-cache.ts

@@ -0,0 +1,120 @@
+/**
+ * Per-endpoint permission cache for environment variable tokens.
+ *
+ * When an env token (e.g., wizard-generated SENTRY_AUTH_TOKEN) gets a 401/403
+ * on a specific endpoint, the (token, method, url_path) tuple is recorded here.
+ * Subsequent requests to the same endpoint skip the env token and fall back to
+ * stored OAuth credentials.
+ *
+ * Entries expire after {@link ENV_TOKEN_CACHE_TTL_MS} (24 hours) to handle
+ * internal integration tokens whose scopes can be edited without changing the
+ * token string. Expired entries are ignored on read and cleaned up lazily by
+ * the probabilistic cleanup in `cleanupExpiredCaches()`.
+ */
+
+import { withDbSpan } from "../telemetry.js";
+import { getDatabase, maybeCleanupCaches } from "./index.js";
+import { runUpsert } from "./utils.js";
+
+/** 24-hour TTL for env token permission cache entries */
+export const ENV_TOKEN_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Check if a specific endpoint is marked as insufficient for the given token.
+ *
+ * Returns `false` if no entry exists or if the entry is older than the TTL.
+ * This ensures that stale marks are functionally ignored even before the
+ * probabilistic cleanup physically deletes them.
+ */
+export function isEndpointInsufficient(
+  token: string,
+  method: string,
+  urlPath: string
+): boolean {
+  return withDbSpan("isEndpointInsufficient", () => {
+    const db = getDatabase();
+    const minCreatedAt = Date.now() - ENV_TOKEN_CACHE_TTL_MS;
+    const row = db
+      .query(
+        "SELECT 1 FROM env_token_permissions " +
+          "WHERE token = ? AND method = ? AND url_path = ? AND created_at > ?"
+      )
+      .get(token, method, urlPath, minCreatedAt);
+    return row !== null;
+  });
+}
+
+/**
+ * Mark a specific endpoint as insufficient for the given token.
+ *
+ * Uses UPSERT so re-encountering the same failure refreshes `created_at`,
+ * extending the TTL. Triggers probabilistic cache cleanup (10% chance).
+ *
+ * @param token - The full env token string
+ * @param method - HTTP method (e.g., "GET", "POST")
+ * @param urlPath - URL pathname without query params (e.g., "/api/0/organizations/my-org/issues/")
+ * @param status - HTTP status code that triggered the mark (401 or 403)
+ */
+export function markEndpointInsufficient(
+  token: string,
+  method: string,
+  urlPath: string,
+  status: number
+): void {
+  withDbSpan("markEndpointInsufficient", () => {
+    const db = getDatabase();
+    runUpsert(
+      db,
+      "env_token_permissions",
+      {
+        token,
+        method,
+        url_path: urlPath,
+        status,
+        created_at: Date.now(),
+      },
+      ["token", "method", "url_path"]
+    );
+    maybeCleanupCaches();
+  });
+}
+
+/**
+ * Clear all env token permission cache entries.
+ * Called by `clearAuth()` and `applyFreshFlag()`.
+ */
+export function clearEnvTokenCache(): void {
+  withDbSpan("clearEnvTokenCache", () => {
+    const db = getDatabase();
+    db.query("DELETE FROM env_token_permissions").run();
+  });
+}
+
+/**
+ * Clear permission cache entries for a specific token.
+ * Useful when a token is known to have changed.
+ */
+export function clearEnvTokenCacheForToken(token: string): void {
+  withDbSpan("clearEnvTokenCacheForToken", () => {
+    const db = getDatabase();
+    db.query("DELETE FROM env_token_permissions WHERE token = ?").run(token);
+  });
+}
+
+/**
+ * Count the number of endpoints marked as insufficient for a specific token.
+ * Only counts non-expired entries. Used by `auth status` for diagnostics.
+ */
+export function countInsufficientEndpoints(token: string): number {
+  return withDbSpan("countInsufficientEndpoints", () => {
+    const db = getDatabase();
+    const minCreatedAt = Date.now() - ENV_TOKEN_CACHE_TTL_MS;
+    const row = db
+      .query(
+        "SELECT COUNT(*) as count FROM env_token_permissions " +
+          "WHERE token = ? AND created_at > ?"
+      )
+      .get(token, minCreatedAt) as { count: number };
+    return row.count;
+  });
+}

src/lib/db/index.ts

@@ -7,6 +7,7 @@ import { Database } from "bun:sqlite";
 import { chmodSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { getEnv } from "../env.js";
+import { ENV_TOKEN_CACHE_TTL_MS } from "./env-token-cache.js";
 import { migrateFromJson } from "./migration.js";
 import { initSchema, runMigrations } from "./schema.js";
 
@@ -171,6 +172,11 @@ function cleanupExpiredCaches(): void {
   database
     .query("DELETE FROM project_root_cache WHERE ttl_expires_at < ?")
     .run(now);
+  // env_token_permissions uses a 24-hour TTL based on created_at
+  const envTokenExpiryTime = now - ENV_TOKEN_CACHE_TTL_MS;
+  database
+    .query("DELETE FROM env_token_permissions WHERE created_at < ?")
+    .run(envTokenExpiryTime);
 }
 
 export function maybeCleanupCaches(): void {