feat(auth): standardize OAuth2 Basic authentication across SDK

- Update addAuthHeaders() to use OAuth2 Basic auth format
- Uses Authorization: Basic base64(clientId:clientSecret) header
- Remove non-standard X-Client-ID and X-Client-Secret headers
- X-License-Key retained as fallback for backward compatibility
- Add comprehensive tests for OAuth2 Basic auth
- Update CHANGELOG with authentication changes

Author: saurabhjain1592

CHANGELOG.md

@@ -15,6 +15,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Requires enterprise portal authentication
 - **PRRecord.closedAt**: Added optional `closedAt` field to track when a PR was closed
 
+### Changed
+
+- **OAuth2 Basic Authentication**: Standardized authentication to use industry-standard OAuth2 Basic auth
+  - Uses `Authorization: Basic base64(clientId:clientSecret)` header
+  - Removed non-standard `X-Client-ID` and `X-Client-Secret` headers
+  - `X-License-Key` retained for backward compatibility (fallback when OAuth2 credentials not provided)
+  - Matches TypeScript SDK authentication pattern for consistency across all SDKs
+
 ### Fixed
 
 - **getPlanStatus endpoint**: Fixed endpoint path from `/api/v1/orchestrator/plan/{id}` to `/api/v1/plan/{id}` to match agent proxy routes

src/main/java/com/getaxonflow/sdk/AxonFlow.java

@@ -36,7 +36,9 @@
 import java.io.Closeable;
 import java.io.IOException;
 import java.net.URI;
+import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
+import java.util.Base64;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
@@ -1665,16 +1667,20 @@ private void addAuthHeaders(Request.Builder builder) {
             return;
         }
 
-        // Prefer license key
-        if (config.getLicenseKey() != null && !config.getLicenseKey().isEmpty()) {
-            builder.header("X-License-Key", config.getLicenseKey());
+        // OAuth2-style: Authorization: Basic base64(clientId:clientSecret)
+        if (config.getClientId() != null && !config.getClientId().isEmpty() &&
+            config.getClientSecret() != null && !config.getClientSecret().isEmpty()) {
+            String credentials = config.getClientId() + ":" + config.getClientSecret();
+            String encoded = Base64.getEncoder().encodeToString(
+                credentials.getBytes(StandardCharsets.UTF_8)
+            );
+            builder.header("Authorization", "Basic " + encoded);
             return;
         }
 
-        // Fall back to client credentials
-        if (config.getClientId() != null && config.getClientSecret() != null) {
-            builder.header("X-Client-ID", config.getClientId());
-            builder.header("X-Client-Secret", config.getClientSecret());
+        // Fallback: X-License-Key header (backward compatibility)
+        if (config.getLicenseKey() != null && !config.getLicenseKey().isEmpty()) {
+            builder.header("X-License-Key", config.getLicenseKey());
         }
     }
 

src/test/java/com/getaxonflow/sdk/SelfHostedZeroConfigTest.java

@@ -448,7 +448,7 @@ void shouldNotSendAuthHeadersWithoutCredentials(WireMockRuntimeInfo wmRuntimeInf
             // Verify no auth headers were sent when no credentials configured
             verify(postRequestedFor(urlEqualTo("/api/request"))
                 .withoutHeader("X-License-Key")
-                .withoutHeader("X-Client-Secret"));
+                .withoutHeader("Authorization"));
 
             System.out.println("✅ Auth headers not sent in community mode (no credentials)");
         }
@@ -484,5 +484,79 @@ void shouldSendAuthHeadersWithCredentials(WireMockRuntimeInfo wmRuntimeInfo) {
 
             System.out.println("✅ Auth headers sent when credentials are configured");
         }
+
+        @Test
+        @DisplayName("should send OAuth2 Basic auth with clientId and clientSecret")
+        void shouldSendOAuth2BasicAuth(WireMockRuntimeInfo wmRuntimeInfo) {
+            stubFor(post(urlEqualTo("/api/request"))
+                .willReturn(aResponse()
+                    .withStatus(200)
+                    .withHeader("Content-Type", "application/json")
+                    .withBody("{"
+                        + "\"success\": true,"
+                        + "\"data\": {\"answer\": \"test\"}"
+                        + "}")));
+
+            // With OAuth2 credentials
+            AxonFlow client = AxonFlow.create(AxonFlowConfig.builder()
+                .agentUrl(wmRuntimeInfo.getHttpBaseUrl())
+                .clientId("my-client")
+                .clientSecret("my-secret")
+                .build());
+
+            client.executeQuery(
+                ClientRequest.builder()
+                    .userToken("")
+                    .query("Test query")
+                    .build()
+            );
+
+            // Verify OAuth2 Basic auth header is sent
+            String expectedBasic = "Basic " + java.util.Base64.getEncoder().encodeToString(
+                "my-client:my-secret".getBytes(java.nio.charset.StandardCharsets.UTF_8)
+            );
+            verify(postRequestedFor(urlEqualTo("/api/request"))
+                .withHeader("Authorization", equalTo(expectedBasic)));
+
+            System.out.println("✅ OAuth2 Basic auth header sent correctly");
+        }
+
+        @Test
+        @DisplayName("OAuth2 should take priority over license key")
+        void shouldPrioritizeOAuth2OverLicenseKey(WireMockRuntimeInfo wmRuntimeInfo) {
+            stubFor(post(urlEqualTo("/api/request"))
+                .willReturn(aResponse()
+                    .withStatus(200)
+                    .withHeader("Content-Type", "application/json")
+                    .withBody("{"
+                        + "\"success\": true,"
+                        + "\"data\": {\"answer\": \"test\"}"
+                        + "}")));
+
+            // With BOTH OAuth2 credentials AND license key
+            AxonFlow client = AxonFlow.create(AxonFlowConfig.builder()
+                .agentUrl(wmRuntimeInfo.getHttpBaseUrl())
+                .clientId("my-client")
+                .clientSecret("my-secret")
+                .licenseKey("should-be-ignored")
+                .build());
+
+            client.executeQuery(
+                ClientRequest.builder()
+                    .userToken("")
+                    .query("Test query")
+                    .build()
+            );
+
+            // OAuth2 should take priority
+            String expectedBasic = "Basic " + java.util.Base64.getEncoder().encodeToString(
+                "my-client:my-secret".getBytes(java.nio.charset.StandardCharsets.UTF_8)
+            );
+            verify(postRequestedFor(urlEqualTo("/api/request"))
+                .withHeader("Authorization", equalTo(expectedBasic))
+                .withoutHeader("X-License-Key"));
+
+            System.out.println("✅ OAuth2 correctly takes priority over license key");
+        }
     }
 }