Add API key authentication convenience method to WatsonxService builder

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/WatsonxService.java

@@ -13,6 +13,7 @@
 import java.util.concurrent.Executor;
 import com.ibm.watsonx.ai.chat.ChatService;
 import com.ibm.watsonx.ai.core.auth.AuthenticationProvider;
+import com.ibm.watsonx.ai.core.auth.iam.IAMAuthenticator;
 import com.ibm.watsonx.ai.core.http.AsyncHttpClient;
 import com.ibm.watsonx.ai.core.http.SyncHttpClient;
 import com.ibm.watsonx.ai.core.http.interceptors.BearerInterceptor;
@@ -172,9 +173,26 @@ public T timeout(Duration timeout) {
         }
 
         /**
-         * Sets the {@link AuthenticationProvider} used for authenticating requests.
+         * Sets an {@link IAMAuthenticator}-based {@link AuthenticationProvider}, initialized from the provided IBM Cloud API key.
+         * <p>
+         * For alternative authentication mechanisms, use {@link #authenticationProvider(AuthenticationProvider)}.
          *
-         * @param authenticationProvider {@link AuthenticationProvider} instance
+         * @param apiKey IBM Cloud API key
+         */
+        public T apiKey(String apiKey) {
+            requireNonNull(apiKey, "The apiKey must be provided");
+            authenticationProvider = IAMAuthenticator.builder().apiKey(apiKey).build();
+            return (T) this;
+        }
+
+        /**
+         * Sets the {@link AuthenticationProvider} used to authenticate requests.
+         * <p>
+         * Use this method to specify a custom or non-IAM implementation.
+         * <p>
+         * For IBM Cloud IAM authentication, {@link #apiKey(String)} provides a simpler alternative.
+         *
+         * @param authenticationProvider non-null {@link AuthenticationProvider} instance
          */
         public T authenticationProvider(AuthenticationProvider authenticationProvider) {
             this.authenticationProvider = authenticationProvider;

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/chat/ChatService.java

@@ -37,14 +37,14 @@
 import com.ibm.watsonx.ai.core.auth.AuthenticationProvider;
 
 /**
- * Service class to interact with IBM watsonx.ai Text Chat APIs.
+ * Service for interacting with IBM watsonx.ai Text Chat APIs.
  * <p>
  * <b>Example usage:</b>
  *
  * <pre>{@code
  * ChatService chatService = ChatService.builder()
- *     .url("https://...") // or use CloudRegion
- *     .authenticationProvider(authProvider)
+ *     .url("https://...")      // or use CloudRegion
+ *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
  *     .projectId("my-project-id")
  *     .modelId("ibm/granite-3-8b-instruct")
  *     .build();
@@ -55,7 +55,7 @@
  * );
  * }</pre>
  *
- * For more information, see the <a href="https://cloud.ibm.com/apidocs/watsonx-ai#text-chat" target="_blank"> official documentation</a>.
+ * To use a custom authentication mechanism, configure it explicitly with {@link #authenticationProvider(AuthenticationProvider)}.
  *
  * @see AuthenticationProvider
  */
@@ -369,8 +369,8 @@ public CompletableFuture<Void> chatStreaming(List<ChatMessage> messages, ChatPar
      *
      * <pre>{@code
      * ChatService chatService = ChatService.builder()
-     *     .url("https://...") // or use CloudRegion
-     *     .authenticationProvider(authProvider)
+     *     .url("https://...")      // or use CloudRegion
+     *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
      *     .projectId("my-project-id")
      *     .modelId("ibm/granite-3-8b-instruct")
      *     .build();
@@ -381,7 +381,6 @@ public CompletableFuture<Void> chatStreaming(List<ChatMessage> messages, ChatPar
      * );
      * }</pre>
      *
-     * @see AuthenticationProvider
      * @return {@link Builder} instance.
      */
     public static Builder builder() {

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/deployment/DeploymentService.java

@@ -53,13 +53,13 @@
  *
  * <pre>{@code
  * DeploymentService deploymentService = DeploymentService.builder()
- *     .url("https://...") // or use CloudRegion
- *     .authenticationProvider(authProvider)
+ *     .url("https://...")      // or use CloudRegion
+ *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
  *     .build();
  *
  * }</pre>
  *
- * For more information, see the <a href="https://cloud.ibm.com/apidocs/watsonx-ai#deployments-text-chat" target="_blank"> official documentation</a>.
+ * To use a custom authentication mechanism, configure it explicitly with {@link #authenticationProvider(AuthenticationProvider)}. *
  *
  * @see AuthenticationProvider
  */
@@ -332,17 +332,11 @@ public ForecastResponse forecast(TimeSeriesRequest timeSeriesRequest) {
      *
      * <pre>{@code
      * DeploymentService deploymentService = DeploymentService.builder()
-     *     .url("https://...") // or use CloudRegion
-     *     .deployment("...")
-     *     .authenticationProvider(authProvider)
+     *     .url("https://...")      // or use CloudRegion
+     *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
      *     .build();
-     *
-     * ChatResponse response = deploymentService.chat(
-     *     UserMessage.text("Tell me a joke")
-     * );
      * }</pre>
      *
-     * @see AuthenticationProvider
      * @return {@link Builder} instance.
      */
     public static Builder builder() {

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/embedding/EmbeddingService.java

@@ -29,8 +29,8 @@
  *
  * <pre>{@code
  * EmbeddingService embeddingService = EmbeddingService.builder()
- *     .url("https://...") // or use CloudRegion
- *     .authenticationProvider(authProvider)
+ *     .url("https://...")      // or use CloudRegion
+ *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
  *     .projectId("my-project-id")
  *     .modelId("ibm/granite-embedding-278m-multilingual")
  *     .build();
@@ -41,7 +41,7 @@
  * );
  * }</pre>
  *
- * For more information, see the <a href="https://cloud.ibm.com/apidocs/watsonx-ai#text-embeddings" target="_blank"> official documentation</a>.
+ * To use a custom authentication mechanism, configure it explicitly with {@link #authenticationProvider(AuthenticationProvider)}.
  *
  * @see AuthenticationProvider
  */
@@ -144,8 +144,8 @@ public EmbeddingResponse embedding(List<String> inputs, EmbeddingParameters para
      *
      * <pre>{@code
      * EmbeddingService embeddingService = EmbeddingService.builder()
-     *     .url("https://...") // or use CloudRegion
-     *     .authenticationProvider(authProvider)
+     *     .url("https://...")      // or use CloudRegion
+     *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
      *     .projectId("my-project-id")
      *     .modelId("ibm/granite-embedding-278m-multilingual")
      *     .build();
@@ -156,7 +156,6 @@ public EmbeddingResponse embedding(List<String> inputs, EmbeddingParameters para
      * );
      * }</pre>
      *
-     * @see AuthenticationProvider
      * @return {@link Builder} instance.
      */
     public static Builder builder() {

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/foundationmodel/FoundationModelService.java

@@ -36,9 +36,6 @@
  * var maxSequenceLength = result.maxSequenceLength();
  * }</pre>
  *
- * For more information, see the <a href="https://cloud.ibm.com/apidocs/watsonx-ai#list-foundation-model-specs" target="_blank"> official
- * documentation</a>.
- *
  * @see AuthenticationProvider
  */
 public final class FoundationModelService extends WatsonxService {
@@ -222,7 +219,6 @@ public FoundationModelResponse<FoundationModelTask> getTasks(FoundationModelPara
      * var maxSequenceLength = result.maxSequenceLength();
      * }</pre>
      *
-     * @see AuthenticationProvider
      * @return {@link Builder} instance.
      */
     public static Builder builder() {

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/rerank/RerankService.java

@@ -29,8 +29,8 @@
  *
  * <pre>{@code
  * RerankService rerankService = RerankService.builder()
- *     .url("https://...") // or use CloudRegion
- *     .authenticationProvider(authProvider)
+ *     .url("https://...")      // or use CloudRegion
+ *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
  *     .projectId("my-project-id")
  *     .modelId("cross-encoder/ms-marco-minilm-l-12-v2")
  *     .build();
@@ -44,7 +44,7 @@
  * );
  * }</pre>
  *
- * For more information, see the <a href="https://cloud.ibm.com/apidocs/watsonx-ai#text-rerank" target="_blank"> official documentation</a>.
+ * To use a custom authentication mechanism, configure it explicitly with {@link #authenticationProvider(AuthenticationProvider)}.
  *
  * @see AuthenticationProvider
  */
@@ -128,8 +128,8 @@ public RerankResponse rerank(String query, List<String> inputs, RerankParameters
      *
      * <pre>{@code
      * RerankService rerankService = RerankService.builder()
-     *     .url("https://...") // or use CloudRegion
-     *     .authenticationProvider(authProvider)
+     *     .url("https://...")      // or use CloudRegion
+     *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
      *     .projectId("my-project-id")
      *     .modelId("cross-encoder/ms-marco-minilm-l-12-v2")
      *     .build();
@@ -143,7 +143,6 @@ public RerankResponse rerank(String query, List<String> inputs, RerankParameters
      * );
      * }</pre>
      *
-     * @see AuthenticationProvider
      * @return {@link Builder} instance.
      */
     public static Builder builder() {

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/textextraction/TextExtractionService.java

@@ -51,9 +51,9 @@
  *
  * <pre>{@code
  * TextExtractionService textExtractionService = TextExtractionService.builder()
- *   .url("https://...") // or use CloudRegion
- *   .cosUrl("https://...") // or use CosUrl
- *   .authenticationProvider(authProvider)
+ *   .url("https://...")        // or use CloudRegion
+ *   .cosUrl("https://...")     // or use CosUrl
+ *   .apiKey("my-api-key")      // creates an IAM-based AuthenticationProvider
  *   .projectId("my-project-id")
  *   .documentReference("<connection_id>", "<bucket-name")
  *   .resultReference("<connection_id>", "<bucket-name")
@@ -62,7 +62,7 @@
  * TextExtractionResponse response = textExtractionService.startExtraction("myfile.pdf")
  * }</pre>
  *
- * For more information, see the <a href="https://cloud.ibm.com/apidocs/watsonx-ai#text-extraction" target="_blank"> official documentation</a>.
+ * To use a custom authentication mechanism, configure it explicitly with {@link #authenticationProvider(AuthenticationProvider)}.
  *
  * @see AuthenticationProvider
  */
@@ -824,9 +824,9 @@ private InputStream getExtractedText(String requestId, TextExtractionResponse te
      *
      * <pre>{@code
      * TextExtractionService textExtractionService = TextExtractionService.builder()
-     *   .url("https://...") // or use CloudRegion
-     *   .cosUrl("https://...") // or use CosUrl
-     *   .authenticationProvider(authProvider)
+     *   .url("https://...")        // or use CloudRegion
+     *   .cosUrl("https://...")     // or use CosUrl
+     *   .apiKey("my-api-key")      // creates an IAM-based AuthenticationProvider
      *   .projectId("my-project-id")
      *   .documentReference("<connection_id>", "<bucket-name")
      *   .resultReference("<connection_id>", "<bucket-name")
@@ -835,7 +835,6 @@ private InputStream getExtractedText(String requestId, TextExtractionResponse te
      * TextExtractionResponse response = textExtractionService.startExtraction("myfile.pdf")
      * }</pre>
      *
-     * @see AuthenticationProvider
      * @return {@link Builder} instance.
      */
     public static Builder builder() {

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/textgeneration/TextGenerationService.java

@@ -32,16 +32,16 @@
  *
  * <pre>{@code
  * TextGenerationService textGenerationService = TextGenerationService.builder()
- *     .url("https://...") // or use CloudRegion
- *     .authenticationProvider(authProvider)
+ *     .url("https://...")      // or use CloudRegion
+ *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
  *     .projectId("my-project-id")
  *     .modelId("ibm/granite-13b-instruct-v2")
  *     .build();
  *
  * TextGenerationResponse response = textGenerationService.generate("Hello!");
  * }</pre>
  *
- * For more information, see the <a href="https://cloud.ibm.com/apidocs/watsonx-ai#text-generation" target="_blank"> official documentation</a>.
+ * To use a custom authentication mechanism, configure it explicitly with {@link #authenticationProvider(AuthenticationProvider)}.
  *
  * @see AuthenticationProvider
  */
@@ -223,16 +223,15 @@ public CompletableFuture<Void> generateStreaming(String input, TextGenerationPar
      *
      * <pre>{@code
      * TextGenerationService textGenerationService = TextGenerationService.builder()
-     *     .url("https://...") // or use CloudRegion
-     *     .authenticationProvider(authProvider)
+     *     .url("https://...")      // or use CloudRegion
+     *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
      *     .projectId("my-project-id")
      *     .modelId("ibm/granite-13b-instruct-v2")
      *     .build();
      *
      * TextGenerationResponse response = textGenerationService.generate("Hello!");
      * }</pre>
      *
-     * @see AuthenticationProvider
      * @return {@link Builder} instance.
      */
     public static Builder builder() {

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/timeseries/TimeSeriesService.java

@@ -28,8 +28,8 @@
  *
  * <pre>{@code
  * TimeSeriesService tsService = TimeSeriesService.builder()
- *     .url("https://...") // or use CloudRegion
- *     .authenticationProvider(authProvider)
+ *     .url("https://...")      // or use CloudRegion
+ *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
  *     .projectId("my-project-id")
  *     .modelId("ibm/granite-ttm-1536-96-r2")
  *     .build();
@@ -54,7 +54,7 @@
  * ForecastResponse response = tsService.forecast(request);
  * }</pre>
  *
- * For more information, see the <a href="https://cloud.ibm.com/apidocs/watsonx-ai#time-series-forecast" target="_blank"> official documentation</a>.
+ * To use a custom authentication mechanism, configure it explicitly with {@link #authenticationProvider(AuthenticationProvider)}.
  *
  * @see AuthenticationProvider
  */
@@ -149,8 +149,8 @@ public ForecastResponse forecast(InputSchema inputSchema, ForecastData data, Tim
      *
      * <pre>{@code
      * TimeSeriesService tsService = TimeSeriesService.builder()
-     *     .url("https://...") // or use CloudRegion
-     *     .authenticationProvider(authProvider)
+     *     .url("https://...")      // or use CloudRegion
+     *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
      *     .projectId("my-project-id")
      *     .modelId("ibm/granite-ttm-1536-96-r2")
      *     .build();
@@ -175,7 +175,6 @@ public ForecastResponse forecast(InputSchema inputSchema, ForecastData data, Tim
      * ForecastResponse response = tsService.forecast(request);
      * }</pre>
      *
-     * @see AuthenticationProvider
      * @return {@link Builder} instance.
      */
     public static Builder builder() {

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/tokenization/TokenizationService.java

@@ -28,16 +28,16 @@
  *
  * <pre>{@code
  * TokenizationService tokenizationService = TokenizationService.builder()
- *     .url("https://...") // or use CloudRegion
- *     .authenticationProvider(authProvider)
+ *     .url("https://...")      // or use CloudRegion
+ *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
  *     .projectId("my-project-id")
  *     .modelId("ibm/granite-3-8b-instruct")
  *     .build();
  *
  * TokenizationResponse response = tokenizationService.tokenize("Tell me a joke");
  * }</pre>
  *
- * For more information, see the <a href="https://cloud.ibm.com/apidocs/watsonx-ai#text-tokenization" target="_blank"> official documentation</a>.
+ * To use a custom authentication mechanism, configure it explicitly with {@link #authenticationProvider(AuthenticationProvider)}.
  *
  * @see AuthenticationProvider
  */
@@ -148,16 +148,15 @@ private HttpRequest buildHttpRequest(String input, TokenizationParameters parame
      *
      * <pre>{@code
      * TokenizationService tokenizationService = TokenizationService.builder()
-     *     .url("https://...") // or use CloudRegion
-     *     .authenticationProvider(authProvider)
+     *     .url("https://...")      // or use CloudRegion
+     *     .apiKey("my-api-key")    // creates an IAM-based AuthenticationProvider
      *     .projectId("my-project-id")
      *     .modelId("ibm/granite-3-8b-instruct")
      *     .build();
      *
      * TokenizationResponse response = tokenizationService.tokenize("Tell me a joke");
      * }</pre>
      *
-     * @see AuthenticationProvider
      * @return {@link Builder} instance.
      */
     public static Builder builder() {