Add API key authentication convenience method to WatsonxService builder

Introduced a new `apiKey(String apiKey)` method in the `WatsonxService.Builder` class to simplify IAM authentication setup.
This method internally creates an `IAMAuthenticator` instance using the provided IBM Cloud API key

Signed-off-by: andreadimaio <[email protected]>

Author: andreadimaio

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/test/java/com/ibm/watsonx/ai/chat/ChatServiceTest.java

@@ -30,6 +30,7 @@
 import static org.mockito.Mockito.inOrder;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.spy;
 import static org.mockito.Mockito.when;
 import java.io.File;
 import java.io.IOException;
@@ -3287,4 +3288,34 @@ void test_thinking_without_extraction_tags() {
                 "Extraction tags are required when using control messages");
         });
     }
+
+    @Test
+    void test_builder_with_api_key() {
+
+        withWatsonxServiceMock(() -> {
+
+            var chatServiceBuilder = ChatService.builder()
+                .apiKey("my-api-key");
+
+            assertNotNull(chatServiceBuilder.getAuthenticationProvider());
+            var spyAuthenticator = spy(chatServiceBuilder.getAuthenticationProvider());
+
+            when(mockHttpResponse.statusCode()).thenReturn(200);
+            when(mockHttpResponse.body()).thenReturn(
+                """
+                    {
+                        "access_token": "my-super-token",
+                        "refresh_token": "not_supported",
+                        "ims_user_id": 14364907,
+                        "token_type": "Bearer",
+                        "expires_in": 3600,
+                        "expiration": 1757106813,
+                        "scope": "ibm openid"
+                    }""");
+
+            mockHttpClientSend(mockHttpRequest.capture(), any(BodyHandler.class));
+            spyAuthenticator.token();
+            assertEquals("grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=my-api-key", bodyPublisherToString(mockHttpRequest));
+        });
+    }
 }

modules/watsonx-ai/src/test/java/com/ibm/watsonx/ai/it/ChatServiceIT.java

@@ -72,9 +72,9 @@ void test_chat() {
 
             var chatService = ChatService.builder()
                 .url(URL)
+                .apiKey(API_KEY)
                 .projectId(PROJECT_ID)
                 .modelId("ibm/granite-3-3-8b-instruct")
-                .authenticationProvider(authentication)
                 .logRequests(true)
                 .logResponses(true)
                 .build();