diff --git a/NEXT_CHANGELOG.md b/NEXT_CHANGELOG.md
index 8f5e9e908..3a6e10b3e 100644
--- a/NEXT_CHANGELOG.md
+++ b/NEXT_CHANGELOG.md
@@ -10,6 +10,8 @@
 
 ### Documentation
 
+* Clarify behavior and expectation for method `CredentialsProvider.configure()` to return a new `HeaderFactory` instance on each invocation.
+
 ### Internal Changes
 
 ### API Changes
diff --git a/databricks-sdk-java/src/main/java/com/databricks/sdk/core/CredentialsProvider.java b/databricks-sdk-java/src/main/java/com/databricks/sdk/core/CredentialsProvider.java
index bcbc415ba..723c354cf 100644
--- a/databricks-sdk-java/src/main/java/com/databricks/sdk/core/CredentialsProvider.java
+++ b/databricks-sdk-java/src/main/java/com/databricks/sdk/core/CredentialsProvider.java
@@ -1,7 +1,24 @@
 package com.databricks.sdk.core;
 
+/**
+ * CredentialsProvider is an interface that provides a HeaderFactory to authenticate requests to the
+ * Databricks API.
+ */
 public interface CredentialsProvider {
+  /**
+   * Returns the authentication type identifier for this credentials provider.
+   *
+   * @return the authentication type as a string
+   */
   String authType();
 
+  /**
+   * Creates and returns a new HeaderFactory to authenticate requests to the Databricks API.
+   *
+   * <p>Note: A new HeaderFactory instance is returned on each invocation.
+   *
+   * @param config the Databricks configuration to use for authentication
+   * @return a new HeaderFactory configured for authenticating API requests
+   */
   HeaderFactory configure(DatabricksConfig config);
 }