From 807421a27d2929dff337e9a47b54963964ebfe37 Mon Sep 17 00:00:00 2001
From: Mihai Mitrea <mihai.mitrea@databricks.com>
Date: Tue, 17 Mar 2026 09:40:45 +0000
Subject: [PATCH 1/2] Add --force-refresh flag to `auth token` command

Wire a new --force-refresh CLI flag that delegates to the SDK's
ForceRefreshToken() method, bypassing the cached token validity
check. The default path through Token() is unchanged.

Note: this will not compile until the SDK ships ForceRefreshToken().
---
 NEXT_CHANGELOG.md                             |  1 +
 .../out.test.toml                             |  5 ++
 .../output.txt                                |  4 ++
 .../script                                    |  4 ++
 .../test.toml                                 |  8 +++
 .../force-refresh-no-cache/out.test.toml      |  5 ++
 .../token/force-refresh-no-cache/output.txt   |  3 +
 .../auth/token/force-refresh-no-cache/script  |  3 +
 .../token/force-refresh-success/out.test.toml |  5 ++
 .../token/force-refresh-success/output.txt    |  3 +
 .../auth/token/force-refresh-success/script   |  4 ++
 acceptance/cmd/auth/token/script.prepare      | 31 ++++++++++
 cmd/auth/token.go                             | 22 +++++--
 cmd/auth/token_test.go                        | 61 +++++++++++++++++++
 14 files changed, 155 insertions(+), 4 deletions(-)
 create mode 100644 acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/out.test.toml
 create mode 100644 acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/output.txt
 create mode 100644 acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/script
 create mode 100644 acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/test.toml
 create mode 100644 acceptance/cmd/auth/token/force-refresh-no-cache/out.test.toml
 create mode 100644 acceptance/cmd/auth/token/force-refresh-no-cache/output.txt
 create mode 100644 acceptance/cmd/auth/token/force-refresh-no-cache/script
 create mode 100644 acceptance/cmd/auth/token/force-refresh-success/out.test.toml
 create mode 100644 acceptance/cmd/auth/token/force-refresh-success/output.txt
 create mode 100644 acceptance/cmd/auth/token/force-refresh-success/script
 create mode 100644 acceptance/cmd/auth/token/script.prepare

diff --git a/NEXT_CHANGELOG.md b/NEXT_CHANGELOG.md
index bdf1483d09..93f8240dd6 100644
--- a/NEXT_CHANGELOG.md
+++ b/NEXT_CHANGELOG.md
@@ -7,6 +7,7 @@
 - Add `bundle.engine` config setting to select the deployment engine (`terraform` or `direct`). The `DATABRICKS_BUNDLE_ENGINE` environment variable takes precedence over this setting. When the configured engine doesn't match existing deployment state, a warning is issued and the existing engine is used ([#4749](https://github.com/databricks/cli/pull/4749)).
 
 ### CLI
+* Add `--force-refresh` flag to `databricks auth token` to force a token refresh even when the cached token is still valid ([#4564](https://github.com/databricks/cli/issues/4564)).
 
 ### Bundles
 * engine/direct: Fix permanent drift on experiment name field ([#4627](https://github.com/databricks/cli/pull/4627))
diff --git a/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/out.test.toml b/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/out.test.toml
new file mode 100644
index 0000000000..d560f1de04
--- /dev/null
+++ b/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/out.test.toml
@@ -0,0 +1,5 @@
+Local = true
+Cloud = false
+
+[EnvMatrix]
+  DATABRICKS_BUNDLE_ENGINE = ["terraform", "direct"]
diff --git a/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/output.txt b/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/output.txt
new file mode 100644
index 0000000000..f1a1b8cadb
--- /dev/null
+++ b/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/output.txt
@@ -0,0 +1,4 @@
+Error: A new access token could not be retrieved because the refresh token is invalid. To reauthenticate, run the following command:
+  $ databricks auth login --profile test-profile
+
+Exit code: 1
diff --git a/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/script b/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/script
new file mode 100644
index 0000000000..b5f5c297bc
--- /dev/null
+++ b/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/script
@@ -0,0 +1,4 @@
+setup_test_profile
+setup_test_token_cache
+
+errcode $CLI auth token --profile test-profile --force-refresh
diff --git a/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/test.toml b/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/test.toml
new file mode 100644
index 0000000000..f93632544f
--- /dev/null
+++ b/acceptance/cmd/auth/token/force-refresh-invalid-refresh-token/test.toml
@@ -0,0 +1,8 @@
+Ignore = [
+    "home"
+]
+
+[[Server]]
+Pattern = "POST /oidc/v1/token"
+Response.StatusCode = 401
+Response.Body = '{"error": "invalid_request", "error_description": "Refresh token is invalid"}'
diff --git a/acceptance/cmd/auth/token/force-refresh-no-cache/out.test.toml b/acceptance/cmd/auth/token/force-refresh-no-cache/out.test.toml
new file mode 100644
index 0000000000..d560f1de04
--- /dev/null
+++ b/acceptance/cmd/auth/token/force-refresh-no-cache/out.test.toml
@@ -0,0 +1,5 @@
+Local = true
+Cloud = false
+
+[EnvMatrix]
+  DATABRICKS_BUNDLE_ENGINE = ["terraform", "direct"]
diff --git a/acceptance/cmd/auth/token/force-refresh-no-cache/output.txt b/acceptance/cmd/auth/token/force-refresh-no-cache/output.txt
new file mode 100644
index 0000000000..a5fb246734
--- /dev/null
+++ b/acceptance/cmd/auth/token/force-refresh-no-cache/output.txt
@@ -0,0 +1,3 @@
+Error: cache: databricks OAuth is not configured for this host. Try logging in again with `databricks auth login --profile test-profile` before retrying. If this fails, please report this issue to the Databricks CLI maintainers at https://github.com/databricks/cli/issues/new
+
+Exit code: 1
diff --git a/acceptance/cmd/auth/token/force-refresh-no-cache/script b/acceptance/cmd/auth/token/force-refresh-no-cache/script
new file mode 100644
index 0000000000..e561647987
--- /dev/null
+++ b/acceptance/cmd/auth/token/force-refresh-no-cache/script
@@ -0,0 +1,3 @@
+setup_test_profile
+
+errcode $CLI auth token --profile test-profile --force-refresh
diff --git a/acceptance/cmd/auth/token/force-refresh-success/out.test.toml b/acceptance/cmd/auth/token/force-refresh-success/out.test.toml
new file mode 100644
index 0000000000..d560f1de04
--- /dev/null
+++ b/acceptance/cmd/auth/token/force-refresh-success/out.test.toml
@@ -0,0 +1,5 @@
+Local = true
+Cloud = false
+
+[EnvMatrix]
+  DATABRICKS_BUNDLE_ENGINE = ["terraform", "direct"]
diff --git a/acceptance/cmd/auth/token/force-refresh-success/output.txt b/acceptance/cmd/auth/token/force-refresh-success/output.txt
new file mode 100644
index 0000000000..0b965964ac
--- /dev/null
+++ b/acceptance/cmd/auth/token/force-refresh-success/output.txt
@@ -0,0 +1,3 @@
+
+>>> [CLI] auth token --profile test-profile --force-refresh
+"oauth-token"
diff --git a/acceptance/cmd/auth/token/force-refresh-success/script b/acceptance/cmd/auth/token/force-refresh-success/script
new file mode 100644
index 0000000000..e3e1167dd0
--- /dev/null
+++ b/acceptance/cmd/auth/token/force-refresh-success/script
@@ -0,0 +1,4 @@
+setup_test_profile
+setup_test_token_cache
+
+trace $CLI auth token --profile test-profile --force-refresh | jq .access_token
diff --git a/acceptance/cmd/auth/token/script.prepare b/acceptance/cmd/auth/token/script.prepare
new file mode 100644
index 0000000000..afdf008034
--- /dev/null
+++ b/acceptance/cmd/auth/token/script.prepare
@@ -0,0 +1,31 @@
+setup_test_profile() {
+    export DATABRICKS_HOST_ORIG="$DATABRICKS_HOST"
+
+    sethome "./home"
+    unset DATABRICKS_HOST
+    unset DATABRICKS_TOKEN
+    unset DATABRICKS_CONFIG_PROFILE
+
+    cat > "./home/.databrickscfg" <<ENDCFG
+[test-profile]
+host = $DATABRICKS_HOST_ORIG
+auth_type = databricks-cli
+ENDCFG
+}
+
+setup_test_token_cache() {
+    mkdir -p "./home/.databricks"
+    cat > "./home/.databricks/token-cache.json" <<ENDCACHE
+{
+  "version": 1,
+  "tokens": {
+    "test-profile": {
+      "access_token": "cached-access-token",
+      "token_type": "Bearer",
+      "refresh_token": "test-refresh-token",
+      "expiry": "2099-01-01T00:00:00Z"
+    }
+  }
+}
+ENDCACHE
+}
diff --git a/cmd/auth/token.go b/cmd/auth/token.go
index 5f695ce6bc..982994773f 100644
--- a/cmd/auth/token.go
+++ b/cmd/auth/token.go
@@ -55,15 +55,20 @@ func newTokenCommand(authArguments *auth.AuthArguments) *cobra.Command {
 		Use:   "token [HOST_OR_PROFILE]",
 		Short: "Get authentication token",
 		Long: `Get authentication token from the local cache in ~/.databricks/token-cache.json.
-Refresh the access token if it is expired. Note: This command only works with
-U2M authentication (using the 'databricks auth login' command). M2M authentication
-using a client ID and secret is not supported.`,
+Refresh the access token if it is expired or close to expiry. Use --force-refresh
+to always refresh regardless of the token's remaining lifetime. Note: This command
+only works with U2M authentication (using the 'databricks auth login' command).
+M2M authentication using a client ID and secret is not supported.`,
 	}
 
 	var tokenTimeout time.Duration
 	cmd.Flags().DurationVar(&tokenTimeout, "timeout", defaultTimeout,
 		"Timeout for acquiring a token.")
 
+	var forceRefresh bool
+	cmd.Flags().BoolVar(&forceRefresh, "force-refresh", false,
+		"Force a token refresh even if the cached token is still valid.")
+
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		ctx := cmd.Context()
 		profileName := ""
@@ -77,6 +82,7 @@ using a client ID and secret is not supported.`,
 			profileName:        profileName,
 			args:               args,
 			tokenTimeout:       tokenTimeout,
+			forceRefresh:       forceRefresh,
 			profiler:           profile.DefaultProfiler,
 			persistentAuthOpts: nil,
 		})
@@ -107,6 +113,9 @@ type loadTokenArgs struct {
 	// tokenTimeout is the timeout for retrieving (and potentially refreshing) an OAuth token.
 	tokenTimeout time.Duration
 
+	// forceRefresh forces a token refresh even if the cached token is still valid.
+	forceRefresh bool
+
 	// profiler is the profiler to use for reading the host and account ID from the .databrickscfg file.
 	profiler profile.Profiler
 
@@ -253,7 +262,12 @@ func loadToken(ctx context.Context, args loadTokenArgs) (*oauth2.Token, error) {
 		helpMsg := helpfulError(ctx, args.profileName, oauthArgument)
 		return nil, fmt.Errorf("%w. %s", err, helpMsg)
 	}
-	t, err := persistentAuth.Token()
+	var t *oauth2.Token
+	if args.forceRefresh {
+		t, err = persistentAuth.ForceRefreshToken()
+	} else {
+		t, err = persistentAuth.Token()
+	}
 	if err != nil {
 		if errors.Is(err, cache.ErrNotFound) {
 			// The error returned by the SDK when the token cache doesn't exist or doesn't contain a token
diff --git a/cmd/auth/token_test.go b/cmd/auth/token_test.go
index aa343eb372..442cbd45aa 100644
--- a/cmd/auth/token_test.go
+++ b/cmd/auth/token_test.go
@@ -135,6 +135,10 @@ func TestToken_loadToken(t *testing.T) {
 				Host:                 "https://m2m.cloud.databricks.com",
 				HasClientCredentials: true,
 			},
+			{
+				Name: "valid-token",
+				Host: "https://valid-token.cloud.databricks.com",
+			},
 		},
 	}
 	tokenCache := &inMemoryTokenCache{
@@ -181,6 +185,11 @@ func TestToken_loadToken(t *testing.T) {
 				RefreshToken: "dup1",
 				Expiry:       time.Now().Add(1 * time.Hour),
 			},
+			"valid-token": {
+				AccessToken:  "cached-access-token",
+				RefreshToken: "valid-token",
+				Expiry:       time.Now().Add(1 * time.Hour),
+			},
 		},
 	}
 	validateToken := func(resp *oauth2.Token) {
@@ -699,6 +708,58 @@ func TestToken_loadToken(t *testing.T) {
 			},
 			validateToken: validateToken,
 		},
+		{
+			name: "default path reuses valid cached token without refresh",
+			args: loadTokenArgs{
+				authArguments: &auth.AuthArguments{},
+				profileName:   "valid-token",
+				args:          []string{},
+				tokenTimeout:  1 * time.Hour,
+				profiler:      profiler,
+				persistentAuthOpts: []u2m.PersistentAuthOption{
+					u2m.WithTokenCache(tokenCache),
+					u2m.WithOAuthEndpointSupplier(&MockApiClient{}),
+				},
+			},
+			validateToken: func(resp *oauth2.Token) {
+				assert.Equal(t, "cached-access-token", resp.AccessToken)
+			},
+		},
+		{
+			name: "force refresh refreshes valid cached token",
+			args: loadTokenArgs{
+				authArguments: &auth.AuthArguments{},
+				profileName:   "valid-token",
+				args:          []string{},
+				tokenTimeout:  1 * time.Hour,
+				forceRefresh:  true,
+				profiler:      profiler,
+				persistentAuthOpts: []u2m.PersistentAuthOption{
+					u2m.WithTokenCache(tokenCache),
+					u2m.WithOAuthEndpointSupplier(&MockApiClient{}),
+					u2m.WithHttpClient(&http.Client{Transport: fixtures.SliceTransport{refreshSuccessTokenResponse}}),
+				},
+			},
+			validateToken: validateToken,
+		},
+		{
+			name: "force refresh preserves error handling on refresh failure",
+			args: loadTokenArgs{
+				authArguments: &auth.AuthArguments{},
+				profileName:   "valid-token",
+				args:          []string{},
+				tokenTimeout:  1 * time.Hour,
+				forceRefresh:  true,
+				profiler:      profiler,
+				persistentAuthOpts: []u2m.PersistentAuthOption{
+					u2m.WithTokenCache(tokenCache),
+					u2m.WithOAuthEndpointSupplier(&MockApiClient{}),
+					u2m.WithHttpClient(&http.Client{Transport: fixtures.SliceTransport{refreshFailureTokenResponse}}),
+				},
+			},
+			wantErr: `A new access token could not be retrieved because the refresh token is invalid. To reauthenticate, run the following command:
+  $ databricks auth login --profile valid-token`,
+		},
 	}
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {

From 4c9a54d75c743b087022b411083550ded62deed7 Mon Sep 17 00:00:00 2001
From: mihaimitrea-db <mihai.mitrea@databricks.com>
Date: Wed, 18 Mar 2026 17:22:14 +0100
Subject: [PATCH 2/2] Apply suggestion from @mihaimitrea-db

---
 NEXT_CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/NEXT_CHANGELOG.md b/NEXT_CHANGELOG.md
index 93f8240dd6..b682604da9 100644
--- a/NEXT_CHANGELOG.md
+++ b/NEXT_CHANGELOG.md
@@ -7,7 +7,7 @@
 - Add `bundle.engine` config setting to select the deployment engine (`terraform` or `direct`). The `DATABRICKS_BUNDLE_ENGINE` environment variable takes precedence over this setting. When the configured engine doesn't match existing deployment state, a warning is issued and the existing engine is used ([#4749](https://github.com/databricks/cli/pull/4749)).
 
 ### CLI
-* Add `--force-refresh` flag to `databricks auth token` to force a token refresh even when the cached token is still valid ([#4564](https://github.com/databricks/cli/issues/4564)).
+* Add `--force-refresh` flag to `databricks auth token` to force a token refresh even when the cached token is still valid ([#4767](https://github.com/databricks/cli/pull/4767)).
 
 ### Bundles
 * engine/direct: Fix permanent drift on experiment name field ([#4627](https://github.com/databricks/cli/pull/4627))