From 46034222b2a63d0e06b5590a1bc5e6e903477501 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Wed, 6 Aug 2025 17:09:18 +0200
Subject: [PATCH 01/31] feat: implement BearerToken OIDC flow

This is a large chagne that requester modifying some internals:
- Extended Endpoint interface with requesturl overload that takes
RestTransportOptions and builds a full request URL instead of
leaving it up to DefaultRestTrasport
- Added ExternalEndpoint that allows sending REST requests to
arbitrary URIs.
- Added a thin wrapper around Nimbus OAuth2 SDK to refresh tokens.
- Made Authorization an interface that can getTokenProvider().
---
 pom.xml                                       |   1 +
 .../client6/v1/api/Authorization.java         |  19 ++-
 .../io/weaviate/client6/v1/api/Config.java    |  28 +++--
 .../client6/v1/api/WeaviateClient.java        |  16 ++-
 .../io/weaviate/client6/v1/internal/Flow.java |   3 +
 .../v1/internal/ReuseTokenProvider.java       |  20 ++++
 .../client6/v1/internal/TokenProvider.java    |  28 ++++-
 .../client6/v1/internal/oidc/OidcConfig.java  |  18 +++
 .../client6/v1/internal/oidc/OidcUtils.java   |  57 +++++++++
 .../internal/oidc/nimbus/BearerTokenFlow.java |  27 +++++
 .../client6/v1/internal/oidc/nimbus/Flow.java |  14 +++
 .../oidc/nimbus/NimbusTokenProvider.java      | 108 ++++++++++++++++++
 .../internal/rest/DefaultRestTransport.java   |  11 +-
 .../client6/v1/internal/rest/Endpoint.java    |   4 +
 .../v1/internal/rest/EndpointBase.java        |   2 +-
 .../v1/internal/rest/ExternalEndpoint.java    |  23 ++++
 .../v1/internal/rest/RestTransport.java       |   2 +
 .../v1/internal/rest/SimpleEndpoint.java      |  14 +++
 .../client6/v1/api/AuthorizationTest.java     |  23 +++-
 19 files changed, 392 insertions(+), 26 deletions(-)
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/Flow.java
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/BearerTokenFlow.java
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/rest/ExternalEndpoint.java

diff --git a/pom.xml b/pom.xml
index bc4980990..c3175b555 100644
--- a/pom.xml
+++ b/pom.xml
@@ -244,6 +244,7 @@
           <artifactId>maven-surefire-plugin</artifactId>
           <version>2.22.2</version>
           <configuration>
+            <trimStackTrace>false</trimStackTrace>
             <argLine>
               <!--
                 Gson (used for JSON serialization) utilizes reflection and needs to be able to access private fields of
diff --git a/src/main/java/io/weaviate/client6/v1/api/Authorization.java b/src/main/java/io/weaviate/client6/v1/api/Authorization.java
index 9bcfc2ed1..7d0db74c9 100644
--- a/src/main/java/io/weaviate/client6/v1/api/Authorization.java
+++ b/src/main/java/io/weaviate/client6/v1/api/Authorization.java
@@ -1,10 +1,21 @@
 package io.weaviate.client6.v1.api;
 
 import io.weaviate.client6.v1.internal.TokenProvider;
-import io.weaviate.client6.v1.internal.TokenProvider.Token;
+import io.weaviate.client6.v1.internal.oidc.OidcConfig;
+import io.weaviate.client6.v1.internal.oidc.OidcUtils;
+import io.weaviate.client6.v1.internal.rest.RestTransport;
 
-public class Authorization {
-  public static TokenProvider apiKey(String apiKey) {
-    return TokenProvider.staticToken(new Token(apiKey));
+public interface Authorization {
+  TokenProvider getTokenProvider(RestTransport transport);
+
+  public static Authorization apiKey(String apiKey) {
+    return __ -> TokenProvider.staticToken(apiKey);
+  }
+
+  public static Authorization bearerToken(String accessToken, String refreshToken, long expiresIn) {
+    return transport -> {
+      OidcConfig oidc = OidcUtils.getConfig(transport);
+      return TokenProvider.bearerToken(oidc, accessToken, refreshToken, expiresIn);
+    };
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/api/Config.java b/src/main/java/io/weaviate/client6/v1/api/Config.java
index a9a6c9dda..60265d63a 100644
--- a/src/main/java/io/weaviate/client6/v1/api/Config.java
+++ b/src/main/java/io/weaviate/client6/v1/api/Config.java
@@ -19,7 +19,7 @@ public record Config(
     String grpcHost,
     int grpcPort,
     Map<String, String> headers,
-    TokenProvider tokenProvider,
+    Authorization authorization,
     TrustManagerFactory trustManagerFactory) {
 
   public static Config of(Function<Custom, ObjectBuilder<Config>> fn) {
@@ -34,15 +34,23 @@ private Config(Builder<?> builder) {
         builder.grpcHost,
         builder.grpcPort,
         builder.headers,
-        builder.tokenProvider,
+        builder.authorization,
         builder.trustManagerFactory);
   }
 
   RestTransportOptions restTransportOptions() {
+    return restTransportOptions(null);
+  }
+
+  RestTransportOptions restTransportOptions(TokenProvider tokenProvider) {
     return new RestTransportOptions(scheme, httpHost, httpPort, headers, tokenProvider, trustManagerFactory);
   }
 
   GrpcChannelOptions grpcTransportOptions() {
+    return grpcTransportOptions(null);
+  }
+
+  GrpcChannelOptions grpcTransportOptions(TokenProvider tokenProvider) {
     return new GrpcChannelOptions(scheme, grpcHost, grpcPort, headers, tokenProvider, trustManagerFactory);
   }
 
@@ -53,7 +61,7 @@ private abstract static class Builder<SELF extends Builder<SELF>> implements Obj
     protected int httpPort;
     protected String grpcHost;
     protected int grpcPort;
-    protected TokenProvider tokenProvider;
+    protected Authorization authorization;
     protected TrustManagerFactory trustManagerFactory;
     protected Map<String, String> headers = new HashMap<>();
 
@@ -144,7 +152,7 @@ private static boolean isWeaviateDomain(String host) {
     public Config build() {
       // For clusters hosted on Weaviate Cloud, Weaviate Embedding Service
       // will be available under the same domain.
-      if (isWeaviateDomain(httpHost) && tokenProvider != null) {
+      if (isWeaviateDomain(httpHost) && authorization != null) {
         setHeader(HEADER_X_WEAVIATE_CLUSTER_URL, "https://" + httpHost + ":" + httpPort);
       }
       return new Config(this);
@@ -203,11 +211,11 @@ public Local grpcPort(int port) {
    * {@link #trustManagerFactory}.
    */
   public static class WeaviateCloud extends Builder<WeaviateCloud> {
-    public WeaviateCloud(String httpHost, TokenProvider tokenProvider) {
-      this(URI.create(httpHost), tokenProvider);
+    public WeaviateCloud(String httpHost, Authorization authorization) {
+      this(URI.create(httpHost), authorization);
     }
 
-    public WeaviateCloud(URI clusterUri, TokenProvider tokenProvider) {
+    public WeaviateCloud(URI clusterUri, Authorization authorization) {
       scheme("https");
       super.httpHost(clusterUri.getHost() != null
           ? clusterUri.getHost() // https://[example.com]/about
@@ -215,7 +223,7 @@ public WeaviateCloud(URI clusterUri, TokenProvider tokenProvider) {
       super.grpcHost("grpc-" + this.httpHost);
       this.httpPort = 443;
       this.grpcPort = 443;
-      this.tokenProvider = tokenProvider;
+      this.authorization = authorization;
     }
 
     /**
@@ -287,8 +295,8 @@ public Custom grpcPort(int port) {
      * Set authorization method. Setting this to {@code null} or omitting
      * will not use any authorization mechanism.
      */
-    public Custom authorization(TokenProvider tokenProvider) {
-      this.tokenProvider = tokenProvider;
+    public Custom authorization(Authorization authorization) {
+      this.authorization = authorization;
       return this;
     }
 
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
index 1e2127e22..9bf5dedd3 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
@@ -22,8 +22,20 @@ public class WeaviateClient implements Closeable {
 
   public WeaviateClient(Config config) {
     this.config = config;
-    this.restTransport = new DefaultRestTransport(config.restTransportOptions());
-    this.grpcTransport = new DefaultGrpcTransport(config.grpcTransportOptions());
+
+    if (config.authorization() == null) {
+      this.restTransport = new DefaultRestTransport(config.restTransportOptions());
+      this.grpcTransport = new DefaultGrpcTransport(config.grpcTransportOptions());
+    } else {
+      try (final var noAuthRest = new DefaultRestTransport(config.restTransportOptions())) {
+        var tokenProvider = config.authorization().getTokenProvider(noAuthRest);
+        this.restTransport = new DefaultRestTransport(config.restTransportOptions(tokenProvider));
+        this.grpcTransport = new DefaultGrpcTransport(config.grpcTransportOptions(tokenProvider));
+      } catch (IOException e) {
+        // TODO: throw WeaviateOAuthException
+        throw new RuntimeException(e);
+      }
+    }
 
     this.collections = new WeaviateCollectionsClient(restTransport, grpcTransport);
   }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/Flow.java b/src/main/java/io/weaviate/client6/v1/internal/Flow.java
new file mode 100644
index 000000000..66114377e
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/Flow.java
@@ -0,0 +1,3 @@
+public interface Flow {
+
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
new file mode 100644
index 000000000..e2f62406f
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
@@ -0,0 +1,20 @@
+package io.weaviate.client6.v1.internal;
+
+/**
+ * ReuseTokenProvider returns the same token as long as its valid and obtains a
+ * new token from a {@link TokenProvider} otherwise.
+ */
+final class ReuseTokenProvider implements TokenProvider {
+  private TokenProvider provider;
+  private Token token;
+
+  // TODO: this will need synchronization
+  @Override
+  public Token getToken() {
+    if (token.isValid()) {
+      return token;
+    }
+    token = provider.getToken();
+    return token;
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index af69a456b..f14d8a791 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -1,13 +1,37 @@
 package io.weaviate.client6.v1.internal;
 
+import java.time.Instant;
+
+import io.weaviate.client6.v1.internal.oidc.OidcConfig;
+import io.weaviate.client6.v1.internal.oidc.nimbus.NimbusTokenProvider;
+
 @FunctionalInterface
 public interface TokenProvider {
   Token getToken();
 
-  public record Token(String accessToken) {
+  public record Token(String accessToken, String refreshToken, Instant createdAt, long expiresIn) {
+    public boolean isValid() {
+      // TODO: adjust for expireDelta
+      return Instant.now().isAfter(createdAt.plusSeconds(expiresIn));
+    }
+
+    public static Token expireAfter(String accessToken, String refreshToken, long expiresIn) {
+      return new Token(accessToken, refreshToken, Instant.now(), expiresIn);
+    }
+
+    /** Create a token that never expires. */
+    public static Token expireNever(String accessToken) {
+      return Token.expireAfter(accessToken, "", -1);
+    }
   }
 
-  public static TokenProvider staticToken(Token token) {
+  public static TokenProvider staticToken(String accessToken) {
+    final var token = Token.expireNever(accessToken);
     return () -> token;
   }
+
+  public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, String refreshToken, long expiresIn) {
+    final var token = Token.expireAfter(accessToken, refreshToken, expiresIn);
+    return NimbusTokenProvider.bearerToken(oidc, token);
+  }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java
new file mode 100644
index 000000000..48e7ed9fd
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java
@@ -0,0 +1,18 @@
+package io.weaviate.client6.v1.internal.oidc;
+
+import java.util.Collections;
+import java.util.List;
+
+public record OidcConfig(
+    String clientId,
+    String redirectUrl,
+    String providerMetadata,
+    List<String> scopes) {
+
+  public OidcConfig(String clientId, String redirectUrl, String providerMetadata, List<String> scopes) {
+    this.clientId = clientId;
+    this.redirectUrl = redirectUrl;
+    this.providerMetadata = providerMetadata;
+    this.scopes = scopes != null ? scopes : Collections.emptyList();
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
new file mode 100644
index 000000000..78c621889
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
@@ -0,0 +1,57 @@
+package io.weaviate.client6.v1.internal.oidc;
+
+import java.io.IOException;
+import java.util.Collections;
+import java.util.List;
+
+import com.google.gson.annotations.SerializedName;
+
+import io.weaviate.client6.v1.internal.json.JSON;
+import io.weaviate.client6.v1.internal.rest.Endpoint;
+import io.weaviate.client6.v1.internal.rest.ExternalEndpoint;
+import io.weaviate.client6.v1.internal.rest.RestTransport;
+import io.weaviate.client6.v1.internal.rest.SimpleEndpoint;
+
+public final class OidcUtils {
+  private OidcUtils() {
+  }
+
+  private static final String OPENID_URL = "/.well-known/openid-configuration";
+  private static final Endpoint<Void, OpenIdConfiguration> GET_OPENID = SimpleEndpoint.noBody(
+      request -> "GET",
+      request -> "/.well-known/openid-configuration",
+      request -> Collections.emptyMap(),
+      OpenIdConfiguration.class);
+
+  private static final Endpoint<String, String> GET_PROVIDER_METADATA = new ExternalEndpoint<>(
+      request -> "GET",
+      request -> request, // URL is the request body.
+      requesf -> Collections.emptyMap(),
+      request -> null,
+      (statusCode, response) -> JSON.deserialize(response, String.class));
+
+  private static record OpenIdConfiguration(
+      @SerializedName("clientId") String clientId,
+      @SerializedName("scopes") List<String> scopes,
+      @SerializedName("href") String endpoint) {
+  }
+
+  public static final OidcConfig getConfig(RestTransport transport) {
+    OpenIdConfiguration openid;
+    try {
+      openid = transport.performRequest(null, GET_OPENID);
+    } catch (IOException e) {
+      throw new RuntimeException(e);
+    }
+
+    String providerMetadata;
+    try {
+      providerMetadata = transport.performRequest(openid.endpoint(), GET_PROVIDER_METADATA);
+    } catch (IOException e) {
+      throw new RuntimeException(e);
+    }
+
+    var redirectUrl = transport.getTransportOptions().baseUrl() + OPENID_URL;
+    return new OidcConfig(openid.clientId(), redirectUrl, providerMetadata, openid.scopes());
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/BearerTokenFlow.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/BearerTokenFlow.java
new file mode 100644
index 000000000..98904c6ae
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/BearerTokenFlow.java
@@ -0,0 +1,27 @@
+package io.weaviate.client6.v1.internal.oidc.nimbus;
+
+import javax.annotation.concurrent.NotThreadSafe;
+
+import com.nimbusds.oauth2.sdk.AuthorizationGrant;
+import com.nimbusds.oauth2.sdk.RefreshTokenGrant;
+import com.nimbusds.oauth2.sdk.token.RefreshToken;
+
+import io.weaviate.client6.v1.internal.TokenProvider.Token;
+
+@NotThreadSafe
+final class BearerTokenFlow implements Flow {
+  private Token t;
+
+  BearerTokenFlow(Token t) {
+    this.t = t;
+  }
+
+  @Override
+  public AuthorizationGrant getAuthorizationGrant() {
+    return new RefreshTokenGrant(new RefreshToken(t.refreshToken()));
+  }
+
+  public void setToken(Token t) {
+    this.t = t;
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
new file mode 100644
index 000000000..dae185db7
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
@@ -0,0 +1,14 @@
+package io.weaviate.client6.v1.internal.oidc.nimbus;
+
+import com.nimbusds.oauth2.sdk.AuthorizationGrant;
+
+import io.weaviate.client6.v1.internal.TokenProvider.Token;
+
+@FunctionalInterface
+interface Flow {
+  AuthorizationGrant getAuthorizationGrant();
+
+  static Flow bearerToken(Token t) {
+    return new BearerTokenFlow(t);
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
new file mode 100644
index 000000000..dcbfa6b51
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
@@ -0,0 +1,108 @@
+package io.weaviate.client6.v1.internal.oidc.nimbus;
+
+import java.io.IOException;
+
+import javax.annotation.concurrent.NotThreadSafe;
+
+import com.nimbusds.oauth2.sdk.AuthorizationGrant;
+import com.nimbusds.oauth2.sdk.ParseException;
+import com.nimbusds.oauth2.sdk.RefreshTokenGrant;
+import com.nimbusds.oauth2.sdk.Scope;
+import com.nimbusds.oauth2.sdk.TokenErrorResponse;
+import com.nimbusds.oauth2.sdk.TokenRequest;
+import com.nimbusds.oauth2.sdk.TokenResponse;
+import com.nimbusds.oauth2.sdk.id.ClientID;
+import com.nimbusds.oauth2.sdk.token.RefreshToken;
+import com.nimbusds.openid.connect.sdk.OIDCTokenResponse;
+import com.nimbusds.openid.connect.sdk.OIDCTokenResponseParser;
+import com.nimbusds.openid.connect.sdk.op.OIDCProviderMetadata;
+
+import io.weaviate.client6.v1.internal.TokenProvider;
+import io.weaviate.client6.v1.internal.oidc.OidcConfig;
+
+@NotThreadSafe
+public final class NimbusTokenProvider implements TokenProvider {
+  private final OIDCProviderMetadata metadata;
+  private final ClientID clientId;
+  private final Scope scope;
+  private final String redirectUrl;
+  private final Flow flow;
+
+  public static NimbusTokenProvider bearerToken(OidcConfig oidc, Token t) {
+    return new NimbusTokenProvider(oidc, Flow.bearerToken(t));
+  }
+
+  private NimbusTokenProvider(OidcConfig oidc, Flow flow) {
+    try {
+      this.metadata = OIDCProviderMetadata.parse(oidc.providerMetadata());
+    } catch (ParseException ex) {
+      // TODO: throw WeaviateOAuthException;
+      throw new RuntimeException(ex);
+    }
+
+    this.clientId = new ClientID(oidc.clientId());
+    this.scope = new Scope(oidc.scopes().toArray(String[]::new));
+    this.redirectUrl = oidc.redirectUrl();
+    this.flow = flow;
+  }
+
+  @Override
+  public Token getToken() {
+    var uri = metadata.getTokenEndpointURI();
+    var grant = flow.getAuthorizationGrant();
+    var request = new TokenRequest.Builder(uri, clientId, grant)
+        .scope(scope)
+        .customParameter("response_type", "code", "id_token")
+        .customParameter("response_mode", "fragment")
+        .customParameter("redirect_url", redirectUrl)
+        .build().toHTTPRequest();
+
+    TokenResponse response;
+    try {
+      var httpResponse = request.send();
+      response = OIDCTokenResponseParser.parse(httpResponse);
+    } catch (IOException | ParseException e) {
+      // TODO: throw WeaviateOAuthException
+      throw new RuntimeException(e);
+    }
+
+    if (response instanceof TokenErrorResponse err) {
+      var message = err.getErrorObject().getDescription();
+      // TODO: throw WeaviateOAuthException
+      throw new RuntimeException(message);
+    }
+
+    var tokens = ((OIDCTokenResponse) response).getOIDCTokens();
+    var accessToken = tokens.getAccessToken();
+    var refreshToken = tokens.getRefreshToken();
+
+    var newToken = Token.expireAfter(
+        accessToken.getValue(),
+        refreshToken.getValue(),
+        accessToken.getLifetime());
+
+    if (flow instanceof BearerTokenFlow btf) {
+      btf.setToken(newToken);
+    }
+
+    return newToken;
+  }
+
+  @NotThreadSafe
+  final class BearerTokenFlow implements Flow {
+    private Token t;
+
+    BearerTokenFlow(Token t) {
+      this.t = t;
+    }
+
+    @Override
+    public AuthorizationGrant getAuthorizationGrant() {
+      return new RefreshTokenGrant(new RefreshToken(t.refreshToken()));
+    }
+
+    public void setToken(Token t) {
+      this.t = t;
+    }
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java b/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java
index bcd5a07ab..8e011eb23 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java
@@ -79,6 +79,7 @@ public DefaultRestTransport(RestTransportOptions transportOptions) {
   public <RequestT, ResponseT, ExceptionT> ResponseT performRequest(RequestT request,
       Endpoint<RequestT, ResponseT> endpoint)
       throws IOException {
+
     var req = prepareClassicRequest(request, endpoint);
     return this.httpClient.execute(req, r -> this.handleResponse(endpoint, req.getMethod(), req.getRequestUri(), r));
   }
@@ -86,7 +87,7 @@ public <RequestT, ResponseT, ExceptionT> ResponseT performRequest(RequestT reque
   private <RequestT, ResponseT> ClassicHttpRequest prepareClassicRequest(RequestT request,
       Endpoint<RequestT, ResponseT> endpoint) {
     var method = endpoint.method(request);
-    var uri = transportOptions.baseUrl() + endpoint.requestUrl(request);
+    var uri = endpoint.requestUrl(transportOptions, request);
 
     // TODO: apply options;
     var req = ClassicRequestBuilder.create(method).setUri(uri);
@@ -138,7 +139,8 @@ public void cancelled() {
   private <RequestT, ResponseT> SimpleHttpRequest prepareSimpleRequest(RequestT request,
       Endpoint<RequestT, ResponseT> endpoint) {
     var method = endpoint.method(request);
-    var uri = transportOptions.baseUrl() + endpoint.requestUrl(request);
+    var uri = endpoint.requestUrl(transportOptions, request);
+
     // TODO: apply options;
 
     var body = endpoint.body(request);
@@ -181,6 +183,11 @@ private <ResponseT> ResponseT _handleResponse(Endpoint<?, ResponseT> endpoint, S
     throw new RuntimeException("Unhandled endpoint type " + endpoint.getClass().getSimpleName());
   }
 
+  @Override
+  public RestTransportOptions getTransportOptions() {
+    return transportOptions;
+  }
+
   @Override
   public void close() throws IOException {
     httpClient.close();
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/Endpoint.java b/src/main/java/io/weaviate/client6/v1/internal/rest/Endpoint.java
index 52cc37c3b..3eaceeebf 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/Endpoint.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/Endpoint.java
@@ -8,6 +8,10 @@ public interface Endpoint<RequestT, ResponseT> {
 
   String requestUrl(RequestT request);
 
+  default String requestUrl(RestTransportOptions transportOptions, RequestT request) {
+    return transportOptions.baseUrl() + requestUrl(request);
+  }
+
   String body(RequestT request);
 
   Map<String, String> queryParameters(RequestT request);
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/EndpointBase.java b/src/main/java/io/weaviate/client6/v1/internal/rest/EndpointBase.java
index 2ebe61d6d..6cd8d375d 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/EndpointBase.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/EndpointBase.java
@@ -60,7 +60,7 @@ public boolean isError(int statusCode) {
   @Override
   public String deserializeError(int statusCode, String responseBody) {
     var response = JSON.deserialize(responseBody, ErrorResponse.class);
-    if (response.errors.isEmpty()) {
+    if (response == null || response.errors.isEmpty()) {
       return "";
 
     }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/ExternalEndpoint.java b/src/main/java/io/weaviate/client6/v1/internal/rest/ExternalEndpoint.java
new file mode 100644
index 000000000..05a62d3c6
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/ExternalEndpoint.java
@@ -0,0 +1,23 @@
+package io.weaviate.client6.v1.internal.rest;
+
+import java.util.Map;
+import java.util.function.BiFunction;
+import java.util.function.Function;
+
+public class ExternalEndpoint<RequestT, ResponseT> extends SimpleEndpoint<RequestT, ResponseT> {
+
+  public ExternalEndpoint(
+      Function<RequestT, String> method,
+      Function<RequestT, String> requestUrl,
+      Function<RequestT, Map<String, String>> queryParameters,
+      Function<RequestT, String> body,
+      BiFunction<Integer, String, ResponseT> deserializeResponse) {
+    super(method, requestUrl, queryParameters, body, deserializeResponse);
+  }
+
+  /** Returns {@link #requestUrl()} without {@code baseUrl} prefix. */
+  @Override
+  public String requestUrl(RestTransportOptions __, RequestT request) {
+    return requestUrl(request);
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/RestTransport.java b/src/main/java/io/weaviate/client6/v1/internal/rest/RestTransport.java
index 1fc25836b..2b3d50e07 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/RestTransport.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/RestTransport.java
@@ -11,4 +11,6 @@ <RequestT, ResponseT, ExceptionT> ResponseT performRequest(RequestT request,
 
   <RequestT, ResponseT, ExceptionT> CompletableFuture<ResponseT> performRequestAsync(RequestT request,
       Endpoint<RequestT, ResponseT> endpoint);
+
+  RestTransportOptions getTransportOptions();
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/SimpleEndpoint.java b/src/main/java/io/weaviate/client6/v1/internal/rest/SimpleEndpoint.java
index 9f5c6fa9c..5e7bf61f1 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/SimpleEndpoint.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/SimpleEndpoint.java
@@ -4,6 +4,8 @@
 import java.util.function.BiFunction;
 import java.util.function.Function;
 
+import io.weaviate.client6.v1.internal.json.JSON;
+
 public class SimpleEndpoint<RequestT, ResponseT> extends EndpointBase<RequestT, ResponseT>
     implements JsonEndpoint<RequestT, ResponseT> {
   private static final BiFunction<Integer, String, Void> NULL_RESPONSE = (__code, __body) -> null;
@@ -14,6 +16,10 @@ protected static BiFunction<Integer, String, Void> nullResponse() {
     return NULL_RESPONSE;
   }
 
+  protected static <T> BiFunction<Integer, String, T> deserializeClass(Class<T> cls) {
+    return (statusCode, response) -> JSON.deserialize(response, cls);
+  }
+
   public static <RequestT, ResponseT> SimpleEndpoint<RequestT, ResponseT> noBody(
       Function<RequestT, String> method,
       Function<RequestT, String> requestUrl,
@@ -22,6 +28,14 @@ public static <RequestT, ResponseT> SimpleEndpoint<RequestT, ResponseT> noBody(
     return new SimpleEndpoint<>(method, requestUrl, queryParameters, nullBody(), deserializeResponse);
   }
 
+  public static <RequestT, ResponseT> SimpleEndpoint<RequestT, ResponseT> noBody(
+      Function<RequestT, String> method,
+      Function<RequestT, String> requestUrl,
+      Function<RequestT, Map<String, String>> queryParameters,
+      Class<ResponseT> cls) {
+    return new SimpleEndpoint<>(method, requestUrl, queryParameters, nullBody(), deserializeClass(cls));
+  }
+
   public static <RequestT> SimpleEndpoint<RequestT, Void> sideEffect(
       Function<RequestT, String> method,
       Function<RequestT, String> requestUrl,
diff --git a/src/test/java/io/weaviate/client6/v1/api/AuthorizationTest.java b/src/test/java/io/weaviate/client6/v1/api/AuthorizationTest.java
index 8c4d375e0..7e52d41a4 100644
--- a/src/test/java/io/weaviate/client6/v1/api/AuthorizationTest.java
+++ b/src/test/java/io/weaviate/client6/v1/api/AuthorizationTest.java
@@ -3,6 +3,7 @@
 import java.io.IOException;
 import java.util.Collections;
 
+import org.assertj.core.api.Assertions;
 import org.junit.After;
 import org.junit.Before;
 import org.junit.Test;
@@ -10,11 +11,13 @@
 import org.mockserver.model.HttpRequest;
 
 import io.weaviate.client6.v1.internal.rest.DefaultRestTransport;
-import io.weaviate.client6.v1.internal.rest.OptionalEndpoint;
+import io.weaviate.client6.v1.internal.rest.RestTransport;
 import io.weaviate.client6.v1.internal.rest.RestTransportOptions;
+import io.weaviate.client6.v1.internal.rest.SimpleEndpoint;
 
 public class AuthorizationTest {
   private ClientAndServer mockServer;
+  private RestTransport noAuthTransport;
 
   @Before
   public void startMockServer() throws IOException {
@@ -27,17 +30,26 @@ public void startMockServer() throws IOException {
     // if another webserver is listening to that port.
     // We use 0 to let the underlying system find an available port.
     mockServer = ClientAndServer.startClientAndServer(0);
+    noAuthTransport = new DefaultRestTransport(
+        new RestTransportOptions(
+            "http", "localhost", mockServer.getLocalPort(),
+            Collections.emptyMap(), null, null));
   }
 
   @Test
   public void testAuthorization_apiKey() throws IOException {
+    var authz = Authorization.apiKey("my-api-key");
     var transportOptions = new RestTransportOptions(
         "http", "localhost", mockServer.getLocalPort(),
-        Collections.emptyMap(), Authorization.apiKey("my-api-key"), null);
+        Collections.emptyMap(), authz.getTokenProvider(noAuthTransport), null);
 
     try (final var restClient = new DefaultRestTransport(transportOptions)) {
-      restClient.performRequest(null, OptionalEndpoint.noBodyOptional(
-          request -> "GET", request -> "/", request -> null, (code, response) -> null));
+      restClient.performRequest(null, SimpleEndpoint.sideEffect(
+          request -> "GET", request -> "/", request -> null));
+    } catch (WeaviateApiException ex) {
+      if (ex.httpStatusCode() != 404) {
+        Assertions.fail("unexpected error", ex);
+      }
     }
 
     mockServer.verify(
@@ -48,7 +60,8 @@ public void testAuthorization_apiKey() throws IOException {
   }
 
   @After
-  public void stopMockServer() {
+  public void stopMockServer() throws IOException {
     mockServer.stop();
+    noAuthTransport.close();
   }
 }

From 457bd7c4c62a804dd15fc637cd7283aa30fae33d Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 7 Aug 2025 01:17:12 +0200
Subject: [PATCH 02/31] chore: delete old file

---
 src/main/java/io/weaviate/client6/v1/internal/Flow.java | 3 ---
 1 file changed, 3 deletions(-)
 delete mode 100644 src/main/java/io/weaviate/client6/v1/internal/Flow.java

diff --git a/src/main/java/io/weaviate/client6/v1/internal/Flow.java b/src/main/java/io/weaviate/client6/v1/internal/Flow.java
deleted file mode 100644
index 66114377e..000000000
--- a/src/main/java/io/weaviate/client6/v1/internal/Flow.java
+++ /dev/null
@@ -1,3 +0,0 @@
-public interface Flow {
-
-}

From 9f456aaac9b57b1d35db558a08569cf345485dd5 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 7 Aug 2025 01:16:11 +0200
Subject: [PATCH 03/31] feat: throw WeaviateOAuthException when authorization
 flow fails

---
 .../client6/v1/api/WeaviateClient.java        | 13 +++++++-----
 .../v1/api/WeaviateOAuthException.java        | 20 +++++++++++++++++++
 .../client6/v1/internal/oidc/OidcUtils.java   |  5 +++--
 .../oidc/nimbus/NimbusTokenProvider.java      | 14 ++++++-------
 4 files changed, 38 insertions(+), 14 deletions(-)
 create mode 100644 src/main/java/io/weaviate/client6/v1/api/WeaviateOAuthException.java

diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
index 9bf5dedd3..09e4871ec 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
@@ -6,6 +6,7 @@
 
 import io.weaviate.client6.v1.api.collections.WeaviateCollectionsClient;
 import io.weaviate.client6.v1.internal.ObjectBuilder;
+import io.weaviate.client6.v1.internal.TokenProvider;
 import io.weaviate.client6.v1.internal.grpc.DefaultGrpcTransport;
 import io.weaviate.client6.v1.internal.grpc.GrpcTransport;
 import io.weaviate.client6.v1.internal.rest.DefaultRestTransport;
@@ -27,14 +28,16 @@ public WeaviateClient(Config config) {
       this.restTransport = new DefaultRestTransport(config.restTransportOptions());
       this.grpcTransport = new DefaultGrpcTransport(config.grpcTransportOptions());
     } else {
+      TokenProvider tokenProvider;
       try (final var noAuthRest = new DefaultRestTransport(config.restTransportOptions())) {
-        var tokenProvider = config.authorization().getTokenProvider(noAuthRest);
-        this.restTransport = new DefaultRestTransport(config.restTransportOptions(tokenProvider));
-        this.grpcTransport = new DefaultGrpcTransport(config.grpcTransportOptions(tokenProvider));
+        tokenProvider = config.authorization().getTokenProvider(noAuthRest);
       } catch (IOException e) {
-        // TODO: throw WeaviateOAuthException
-        throw new RuntimeException(e);
+        // Generally IOExceptions are caught in TokenProvider internals.
+        // This one may be thrown when noAuthRest transport is auto-closed.
+        throw new WeaviateOAuthException(e);
       }
+      this.restTransport = new DefaultRestTransport(config.restTransportOptions(tokenProvider));
+      this.grpcTransport = new DefaultGrpcTransport(config.grpcTransportOptions(tokenProvider));
     }
 
     this.collections = new WeaviateCollectionsClient(restTransport, grpcTransport);
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateOAuthException.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateOAuthException.java
new file mode 100644
index 000000000..4c2f7931d
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateOAuthException.java
@@ -0,0 +1,20 @@
+package io.weaviate.client6.v1.api;
+
+/**
+ * Exception class thrown by client API message when the request's reached the
+ * server, but the operation did not complete successfully either either due to
+ * a bad request or a server error.
+ */
+public class WeaviateOAuthException extends WeaviateException {
+  public WeaviateOAuthException(String message) {
+    super(message);
+  }
+
+  public WeaviateOAuthException(String message, Throwable cause) {
+    super(message, cause);
+  }
+
+  public WeaviateOAuthException(Throwable cause) {
+    super(cause);
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
index 78c621889..1e6db146b 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
@@ -6,6 +6,7 @@
 
 import com.google.gson.annotations.SerializedName;
 
+import io.weaviate.client6.v1.api.WeaviateOAuthException;
 import io.weaviate.client6.v1.internal.json.JSON;
 import io.weaviate.client6.v1.internal.rest.Endpoint;
 import io.weaviate.client6.v1.internal.rest.ExternalEndpoint;
@@ -41,14 +42,14 @@ public static final OidcConfig getConfig(RestTransport transport) {
     try {
       openid = transport.performRequest(null, GET_OPENID);
     } catch (IOException e) {
-      throw new RuntimeException(e);
+      throw new WeaviateOAuthException("fetch OpenID configuration", e);
     }
 
     String providerMetadata;
     try {
       providerMetadata = transport.performRequest(openid.endpoint(), GET_PROVIDER_METADATA);
     } catch (IOException e) {
-      throw new RuntimeException(e);
+      throw new WeaviateOAuthException("fetch provider metadata", e);
     }
 
     var redirectUrl = transport.getTransportOptions().baseUrl() + OPENID_URL;
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
index dcbfa6b51..779b043e7 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
@@ -17,6 +17,7 @@
 import com.nimbusds.openid.connect.sdk.OIDCTokenResponseParser;
 import com.nimbusds.openid.connect.sdk.op.OIDCProviderMetadata;
 
+import io.weaviate.client6.v1.api.WeaviateOAuthException;
 import io.weaviate.client6.v1.internal.TokenProvider;
 import io.weaviate.client6.v1.internal.oidc.OidcConfig;
 
@@ -36,8 +37,7 @@ private NimbusTokenProvider(OidcConfig oidc, Flow flow) {
     try {
       this.metadata = OIDCProviderMetadata.parse(oidc.providerMetadata());
     } catch (ParseException ex) {
-      // TODO: throw WeaviateOAuthException;
-      throw new RuntimeException(ex);
+      throw new WeaviateOAuthException("parse provider metadata: ", ex);
     }
 
     this.clientId = new ClientID(oidc.clientId());
@@ -62,14 +62,14 @@ public Token getToken() {
       var httpResponse = request.send();
       response = OIDCTokenResponseParser.parse(httpResponse);
     } catch (IOException | ParseException e) {
-      // TODO: throw WeaviateOAuthException
-      throw new RuntimeException(e);
+      throw new WeaviateOAuthException(e);
     }
 
     if (response instanceof TokenErrorResponse err) {
-      var message = err.getErrorObject().getDescription();
-      // TODO: throw WeaviateOAuthException
-      throw new RuntimeException(message);
+      var error = err.getErrorObject();
+      throw new WeaviateOAuthException("%s %s".formatted(
+          error.getCode(),
+          error.getDescription()));
     }
 
     var tokens = ((OIDCTokenResponse) response).getOIDCTokens();

From 42637de3cb2a746cbd0ce3c2c1ae036cc8e9a45f Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 7 Aug 2025 01:25:26 +0200
Subject: [PATCH 04/31] fix: add synchronization on ReuseTokenProvider

Since HTTP client can use a thread pool executor,
token provider is likely to be accessed concurrently.
We only allow 1 thread at a time working with the token
---
 .../io/weaviate/client6/v1/internal/ReuseTokenProvider.java | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
index e2f62406f..48c992de6 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
@@ -1,16 +1,18 @@
 package io.weaviate.client6.v1.internal;
 
+import javax.annotation.concurrent.ThreadSafe;
+
 /**
  * ReuseTokenProvider returns the same token as long as its valid and obtains a
  * new token from a {@link TokenProvider} otherwise.
  */
+@ThreadSafe
 final class ReuseTokenProvider implements TokenProvider {
   private TokenProvider provider;
   private Token token;
 
-  // TODO: this will need synchronization
   @Override
-  public Token getToken() {
+  public synchronized Token getToken() {
     if (token.isValid()) {
       return token;
     }

From f7ad184f0f3fdfd49e654349fd873395a6dd3aa5 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 7 Aug 2025 01:57:49 +0200
Subject: [PATCH 05/31] feat: reuse token from NimbusTokenProvider

---
 .../v1/internal/ReuseTokenProvider.java       | 31 ++++++++++++++++---
 .../client6/v1/internal/TokenProvider.java    |  3 +-
 2 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
index 48c992de6..fb06f0fd2 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
@@ -8,15 +8,38 @@
  */
 @ThreadSafe
 final class ReuseTokenProvider implements TokenProvider {
-  private TokenProvider provider;
-  private Token token;
+  private final TokenProvider provider;
+
+  private volatile Token token;
+
+  public static TokenProvider wrap(Token t, TokenProvider provider) {
+    if (provider instanceof ReuseTokenProvider rtp) {
+      if (t == null) {
+        return rtp; // Use it directly.
+      }
+    }
+
+    if (t == null) {
+      t = provider.getToken();
+    }
+    return new ReuseTokenProvider(t, provider);
+  }
+
+  private ReuseTokenProvider(Token t, TokenProvider provider) {
+    this.provider = provider;
+    this.token = token;
+  }
 
   @Override
-  public synchronized Token getToken() {
+  public Token getToken() {
     if (token.isValid()) {
       return token;
     }
-    token = provider.getToken();
+    synchronized (this) {
+      if (!token.isValid()) {
+        token = provider.getToken();
+      }
+    }
     return token;
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index f14d8a791..ea7970db1 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -32,6 +32,7 @@ public static TokenProvider staticToken(String accessToken) {
 
   public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, String refreshToken, long expiresIn) {
     final var token = Token.expireAfter(accessToken, refreshToken, expiresIn);
-    return NimbusTokenProvider.bearerToken(oidc, token);
+    final var provider = NimbusTokenProvider.bearerToken(oidc, token);
+    return ReuseTokenProvider.wrap(token, provider);
   }
 }

From f13083fa2991055762c4d6acb7f9e87f895c9730 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 7 Aug 2025 02:00:36 +0200
Subject: [PATCH 06/31] fix: never expire token with expiresIn=-1

---
 .../java/io/weaviate/client6/v1/internal/TokenProvider.java    | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index ea7970db1..cd56b595f 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -11,6 +11,9 @@ public interface TokenProvider {
 
   public record Token(String accessToken, String refreshToken, Instant createdAt, long expiresIn) {
     public boolean isValid() {
+      if (expiresIn == -1) {
+        return true;
+      }
       // TODO: adjust for expireDelta
       return Instant.now().isAfter(createdAt.plusSeconds(expiresIn));
     }

From 272aa519941ea4fced266d3ad5f7c8097083c6cb Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 14 Aug 2025 10:33:46 +0200
Subject: [PATCH 07/31] refactor: create rest/grpc transport outside of
 if-block

---
 .../weaviate/client6/v1/api/WeaviateClient.java | 15 +++++++++++----
 .../client6/v1/internal/ReuseTokenProvider.java | 17 +++++++++++------
 .../client6/v1/internal/TokenProvider.java      |  6 +++++-
 .../client6/v1/internal/oidc/OidcUtils.java     | 10 ++++++----
 .../v1/internal/rest/ExternalEndpoint.java      |  2 +-
 5 files changed, 34 insertions(+), 16 deletions(-)

diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
index 09e4871ec..6f2c0ffb1 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
@@ -8,9 +8,11 @@
 import io.weaviate.client6.v1.internal.ObjectBuilder;
 import io.weaviate.client6.v1.internal.TokenProvider;
 import io.weaviate.client6.v1.internal.grpc.DefaultGrpcTransport;
+import io.weaviate.client6.v1.internal.grpc.GrpcChannelOptions;
 import io.weaviate.client6.v1.internal.grpc.GrpcTransport;
 import io.weaviate.client6.v1.internal.rest.DefaultRestTransport;
 import io.weaviate.client6.v1.internal.rest.RestTransport;
+import io.weaviate.client6.v1.internal.rest.RestTransportOptions;
 
 public class WeaviateClient implements Closeable {
   /** Store this for {@link #async()} helper. */
@@ -24,9 +26,11 @@ public class WeaviateClient implements Closeable {
   public WeaviateClient(Config config) {
     this.config = config;
 
+    RestTransportOptions restOpt;
+    GrpcChannelOptions grpcOpt;
     if (config.authorization() == null) {
-      this.restTransport = new DefaultRestTransport(config.restTransportOptions());
-      this.grpcTransport = new DefaultGrpcTransport(config.grpcTransportOptions());
+      restOpt = config.restTransportOptions();
+      grpcOpt = config.grpcTransportOptions();
     } else {
       TokenProvider tokenProvider;
       try (final var noAuthRest = new DefaultRestTransport(config.restTransportOptions())) {
@@ -36,10 +40,13 @@ public WeaviateClient(Config config) {
         // This one may be thrown when noAuthRest transport is auto-closed.
         throw new WeaviateOAuthException(e);
       }
-      this.restTransport = new DefaultRestTransport(config.restTransportOptions(tokenProvider));
-      this.grpcTransport = new DefaultGrpcTransport(config.grpcTransportOptions(tokenProvider));
+      restOpt = config.restTransportOptions(tokenProvider);
+      grpcOpt = config.grpcTransportOptions(tokenProvider);
     }
 
+    this.restTransport = new DefaultRestTransport(restOpt);
+    this.grpcTransport = new DefaultGrpcTransport(grpcOpt);
+
     this.collections = new WeaviateCollectionsClient(restTransport, grpcTransport);
   }
 
diff --git a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
index fb06f0fd2..0fec61e59 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
@@ -12,21 +12,26 @@ final class ReuseTokenProvider implements TokenProvider {
 
   private volatile Token token;
 
-  public static TokenProvider wrap(Token t, TokenProvider provider) {
-    if (provider instanceof ReuseTokenProvider rtp) {
+  /**
+   * Create new {@link ReuseTokenProvider} from another {@link TokenProvider}.
+   * Wrapping an instance ReuseTokenProvider returns that instance,
+   * so this method is safe to call with any TokenProvider.
+   */
+  static TokenProvider wrap(Token t, TokenProvider tp) {
+    if (tp instanceof ReuseTokenProvider rtp) {
       if (t == null) {
         return rtp; // Use it directly.
       }
     }
 
     if (t == null) {
-      t = provider.getToken();
+      t = tp.getToken();
     }
-    return new ReuseTokenProvider(t, provider);
+    return new ReuseTokenProvider(t, tp);
   }
 
-  private ReuseTokenProvider(Token t, TokenProvider provider) {
-    this.provider = provider;
+  private ReuseTokenProvider(Token t, TokenProvider tp) {
+    this.provider = tp;
     this.token = token;
   }
 
diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index cd56b595f..5aab362ce 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -33,9 +33,13 @@ public static TokenProvider staticToken(String accessToken) {
     return () -> token;
   }
 
+  public static TokenProvider reuse(Token t, TokenProvider tp) {
+    return ReuseTokenProvider.wrap(t, tp);
+  }
+
   public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, String refreshToken, long expiresIn) {
     final var token = Token.expireAfter(accessToken, refreshToken, expiresIn);
     final var provider = NimbusTokenProvider.bearerToken(oidc, token);
-    return ReuseTokenProvider.wrap(token, provider);
+    return reuse(token, provider);
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
index 1e6db146b..9305b7a73 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
@@ -18,13 +18,14 @@ private OidcUtils() {
   }
 
   private static final String OPENID_URL = "/.well-known/openid-configuration";
-  private static final Endpoint<Void, OpenIdConfiguration> GET_OPENID = SimpleEndpoint.noBody(
+
+  private static final Endpoint<Void, OpenIdConfiguration> GET_OPENID_ENDPOINT = SimpleEndpoint.noBody(
       request -> "GET",
       request -> "/.well-known/openid-configuration",
       request -> Collections.emptyMap(),
       OpenIdConfiguration.class);
 
-  private static final Endpoint<String, String> GET_PROVIDER_METADATA = new ExternalEndpoint<>(
+  private static final Endpoint<String, String> GET_PROVIDER_METADATA_ENDPOINT = new ExternalEndpoint<>(
       request -> "GET",
       request -> request, // URL is the request body.
       requesf -> Collections.emptyMap(),
@@ -37,17 +38,18 @@ private static record OpenIdConfiguration(
       @SerializedName("href") String endpoint) {
   }
 
+  /** Fetch cluster's OIDC config. */
   public static final OidcConfig getConfig(RestTransport transport) {
     OpenIdConfiguration openid;
     try {
-      openid = transport.performRequest(null, GET_OPENID);
+      openid = transport.performRequest(null, GET_OPENID_ENDPOINT);
     } catch (IOException e) {
       throw new WeaviateOAuthException("fetch OpenID configuration", e);
     }
 
     String providerMetadata;
     try {
-      providerMetadata = transport.performRequest(openid.endpoint(), GET_PROVIDER_METADATA);
+      providerMetadata = transport.performRequest(openid.endpoint(), GET_PROVIDER_METADATA_ENDPOINT);
     } catch (IOException e) {
       throw new WeaviateOAuthException("fetch provider metadata", e);
     }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/ExternalEndpoint.java b/src/main/java/io/weaviate/client6/v1/internal/rest/ExternalEndpoint.java
index 05a62d3c6..110841e75 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/ExternalEndpoint.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/ExternalEndpoint.java
@@ -15,7 +15,7 @@ public ExternalEndpoint(
     super(method, requestUrl, queryParameters, body, deserializeResponse);
   }
 
-  /** Returns {@link #requestUrl()} without {@code baseUrl} prefix. */
+  /** Returns {@code requestUrl} without {@code baseUrl} prefix. */
   @Override
   public String requestUrl(RestTransportOptions __, RequestT request) {
     return requestUrl(request);

From 330a33370275d2b9e18044a25f473f959ea37ef3 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 14 Aug 2025 15:23:42 +0200
Subject: [PATCH 08/31] feat: implement ResouceOwnerPassword flow

Added isLive to both sync/async client to ping the server
---
 .../java/io/weaviate/containers/Weaviate.java | 44 ++++++++++----
 .../integration/OIDCSupportITest.java         | 57 +++++++++++++++++++
 .../client6/v1/api/Authorization.java         |  9 +++
 .../client6/v1/api/IsLiveRequest.java         | 13 +++++
 .../client6/v1/api/WeaviateClient.java        |  5 ++
 .../client6/v1/api/WeaviateClientAsync.java   |  6 ++
 .../client6/v1/internal/ObjectBuilder.java    | 19 +++++++
 .../v1/internal/ReuseTokenProvider.java       |  7 ++-
 .../client6/v1/internal/TokenProvider.java    |  5 ++
 .../client6/v1/internal/oidc/OidcUtils.java   |  3 +-
 .../client6/v1/internal/oidc/nimbus/Flow.java |  6 ++
 .../oidc/nimbus/NimbusTokenProvider.java      | 17 +++---
 .../v1/internal/rest/BooleanEndpoint.java     |  7 +++
 13 files changed, 173 insertions(+), 25 deletions(-)
 create mode 100644 src/it/java/io/weaviate/integration/OIDCSupportITest.java
 create mode 100644 src/main/java/io/weaviate/client6/v1/api/IsLiveRequest.java

diff --git a/src/it/java/io/weaviate/containers/Weaviate.java b/src/it/java/io/weaviate/containers/Weaviate.java
index d08d8a202..e80c62e24 100644
--- a/src/it/java/io/weaviate/containers/Weaviate.java
+++ b/src/it/java/io/weaviate/containers/Weaviate.java
@@ -6,10 +6,13 @@
 import java.util.HashSet;
 import java.util.Map;
 import java.util.Set;
+import java.util.function.Function;
 
 import org.testcontainers.weaviate.WeaviateContainer;
 
+import io.weaviate.client6.v1.api.Config;
 import io.weaviate.client6.v1.api.WeaviateClient;
+import io.weaviate.client6.v1.internal.ObjectBuilder;
 
 public class Weaviate extends WeaviateContainer {
   private WeaviateClient clientInstance;
@@ -17,23 +20,30 @@ public class Weaviate extends WeaviateContainer {
   public static final String VERSION = "1.29.1";
   public static final String DOCKER_IMAGE = "semitechnologies/weaviate";
 
+  public WeaviateClient getClient() {
+    return getClient(ObjectBuilder.identity());
+  }
+
   /**
    * Get a client for the current Weaviate container.
    * As we aren't running tests in parallel at the moment,
    * this is not made thread-safe.
    */
-  public WeaviateClient getClient() {
+  public WeaviateClient getClient(Function<Config.Custom, ObjectBuilder<Config>> fn) {
     // FIXME: control from containers?
     if (!isRunning()) {
       start();
     }
     if (clientInstance == null) {
+      var customFn = ObjectBuilder.partial(fn,
+          conn -> conn
+              .scheme("http")
+              .httpHost(getHost())
+              .grpcHost(getHost())
+              .httpPort(getMappedPort(8080))
+              .grpcPort(getMappedPort(50051)));
       try {
-        clientInstance = WeaviateClient.local(
-            conn -> conn
-                .host(getHost())
-                .httpPort(getMappedPort(8080))
-                .grpcPort(getMappedPort(50051)));
+        clientInstance = WeaviateClient.custom(customFn);
       } catch (Exception e) {
         throw new RuntimeException("create WeaviateClient for Weaviate container", e);
       }
@@ -90,7 +100,22 @@ public Builder withImageInference(String url, String module) {
     }
 
     public Builder enableTelemetry(boolean enable) {
-      telemetry = enable;
+      environment.put("DISABLE_TELEMETRY", Boolean.toString(!enable));
+      return this;
+    }
+
+    public Builder enableAnonymousAccess(boolean enable) {
+      environment.put("AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED", Boolean.toString(enable));
+      return this;
+    }
+
+    public Builder withOIDC(String clientId, String issuer, String usernameClaim, String groupsClaim) {
+      enableAnonymousAccess(false);
+      environment.put("AUTHENTICATION_OIDC_ENABLED", "true");
+      environment.put("AUTHENTICATION_OIDC_CLIENT_ID", clientId);
+      environment.put("AUTHENTICATION_OIDC_ISSUER", issuer);
+      environment.put("AUTHENTICATION_OIDC_USERNAME_CLAIM", usernameClaim);
+      environment.put("AUTHENTICATION_OIDC_GROUPS_CLAIM", groupsClaim);
       return this;
     }
 
@@ -98,12 +123,9 @@ public Weaviate build() {
       var c = new Weaviate(DOCKER_IMAGE + ":" + versionTag);
 
       if (!enableModules.isEmpty()) {
-        c.withEnv("ENABLE_API_BASED_MODULES", "'true'");
+        c.withEnv("ENABLE_API_BASED_MODULES", Boolean.TRUE.toString());
         c.withEnv("ENABLE_MODULES", String.join(",", enableModules));
       }
-      if (!telemetry) {
-        c.withEnv("DISABLE_TELEMETRY", "true");
-      }
 
       environment.forEach((name, value) -> c.withEnv(name, value));
       c.withCreateContainerCmdModifier(cmd -> cmd.withHostName("weaviate"));
diff --git a/src/it/java/io/weaviate/integration/OIDCSupportITest.java b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
new file mode 100644
index 000000000..144cec0c7
--- /dev/null
+++ b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
@@ -0,0 +1,57 @@
+package io.weaviate.integration;
+
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.net.Socket;
+import java.util.List;
+
+import org.assertj.core.api.Assertions;
+import org.junit.Assume;
+import org.junit.Test;
+
+import io.weaviate.ConcurrentTest;
+import io.weaviate.client6.v1.api.Authorization;
+import io.weaviate.containers.Weaviate;
+
+public class OIDCSupportITest extends ConcurrentTest {
+  private static final Weaviate wcsContainer = Weaviate.custom()
+      .withOIDC("wcs", "https://auth.wcs.api.weaviate.io/auth/realms/SeMI", "email", "groups")
+      .build();
+
+  private static final String WCS_DUMMY_CI_USER = System.getenv("WCS_DUMMY_CI_USER");
+  private static final String WCS_DUMMY_CI_PW = System.getenv("WCS_DUMMY_CI_PW");
+  private static final String OKTA_CLIENT_SECRET = System.getenv("OKTA_CLIENT_SECRET");
+
+  @Test
+  public void test_resourceOwnerPassword() throws IOException {
+    checkSkip();
+
+    var authz = Authorization.resourceOwnerPassword(WCS_DUMMY_CI_USER, WCS_DUMMY_CI_PW, List.of("test_scope"));
+
+    try (final var client = wcsContainer.getClient(conn -> conn.authorization(authz))) {
+      Assertions.assertThat(client.isLive()).isTrue();
+    }
+  }
+
+  @Test
+  public void test_bearerToken() {
+    checkSkip();
+  }
+
+  private static void checkSkip() {
+    Assume.assumeTrue("WCS_DUMMY_CI_USER is not set", WCS_DUMMY_CI_USER != null);
+    Assume.assumeTrue("WCS_DUMMY_CI_PW is not set", WCS_DUMMY_CI_PW != null);
+    Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
+    Assume.assumeTrue("no internet connection", ping("www.google.com"));
+  }
+
+  private static boolean ping(String site) {
+    InetSocketAddress addr = new InetSocketAddress(site, 80);
+    try (final var sock = new Socket()) {
+      sock.connect(addr, 3000);
+      return true;
+    } catch (IOException e) {
+      return false;
+    }
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/api/Authorization.java b/src/main/java/io/weaviate/client6/v1/api/Authorization.java
index 7d0db74c9..1bfaa6671 100644
--- a/src/main/java/io/weaviate/client6/v1/api/Authorization.java
+++ b/src/main/java/io/weaviate/client6/v1/api/Authorization.java
@@ -1,5 +1,7 @@
 package io.weaviate.client6.v1.api;
 
+import java.util.List;
+
 import io.weaviate.client6.v1.internal.TokenProvider;
 import io.weaviate.client6.v1.internal.oidc.OidcConfig;
 import io.weaviate.client6.v1.internal.oidc.OidcUtils;
@@ -18,4 +20,11 @@ public static Authorization bearerToken(String accessToken, String refreshToken,
       return TokenProvider.bearerToken(oidc, accessToken, refreshToken, expiresIn);
     };
   }
+
+  public static Authorization resourceOwnerPassword(String username, String password, List<String> scopes) {
+    return transport -> {
+      OidcConfig oidc = OidcUtils.getConfig(transport);
+      return TokenProvider.resourceOwnerPassword(oidc, username, password);
+    };
+  }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/api/IsLiveRequest.java b/src/main/java/io/weaviate/client6/v1/api/IsLiveRequest.java
new file mode 100644
index 000000000..e098a6e09
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/api/IsLiveRequest.java
@@ -0,0 +1,13 @@
+package io.weaviate.client6.v1.api;
+
+import java.util.Collections;
+
+import io.weaviate.client6.v1.internal.rest.BooleanEndpoint;
+import io.weaviate.client6.v1.internal.rest.Endpoint;
+
+public record IsLiveRequest() {
+  public static final Endpoint<Void, Boolean> _ENDPOINT = BooleanEndpoint.noBody(
+      request -> "GET",
+      request -> "/.well-known/live",
+      request -> Collections.emptyMap());
+}
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
index 6f2c0ffb1..cf7787ae9 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
@@ -121,6 +121,11 @@ public static WeaviateClient custom(Function<Config.Custom, ObjectBuilder<Config
     return new WeaviateClient(fn.apply(new Config.Custom()).build());
   }
 
+  /** Ping the server for a liveness check. */
+  public boolean isLive() throws IOException {
+    return this.restTransport.performRequest(null, IsLiveRequest._ENDPOINT);
+  }
+
   /**
    * Close {@link #restTransport} and {@link #grpcTransport}
    * and release associated resources.
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
index 3f144c5e9..0aff9c8c4 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
@@ -2,6 +2,7 @@
 
 import java.io.Closeable;
 import java.io.IOException;
+import java.util.concurrent.CompletableFuture;
 import java.util.function.Function;
 
 import io.weaviate.client6.v1.api.collections.WeaviateCollectionsClientAsync;
@@ -51,6 +52,11 @@ public static WeaviateClientAsync custom(Function<Config.Custom, ObjectBuilder<C
     return new WeaviateClientAsync(Config.of(fn));
   }
 
+  /** Ping the server for a liveness check. */
+  public CompletableFuture<Boolean> isLive() {
+    return this.restTransport.performRequestAsync(null, IsLiveRequest._ENDPOINT);
+  }
+
   /**
    * Close {@link #restTransport} and {@link #grpcTransport}
    * and release associated resources.
diff --git a/src/main/java/io/weaviate/client6/v1/internal/ObjectBuilder.java b/src/main/java/io/weaviate/client6/v1/internal/ObjectBuilder.java
index 550b4266d..a1ed410fc 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ObjectBuilder.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ObjectBuilder.java
@@ -9,6 +9,25 @@ static <B extends ObjectBuilder<T>, T> Function<B, ObjectBuilder<T>> identity()
     return builder -> builder;
   }
 
+  /**
+   * Chain two builder-functions such that {@code partialFn} is applied before
+   * {@code fn}.
+   *
+   * <p>
+   * Usage:
+   *
+   * <pre>{@code
+   *  static final Function<TBuilder, ObjectBuilder<T>> defaultConfig = b -> {...};
+   *  void doWithConfig(Function<TBuilder, ObjectBuilder<T>> fn) {
+   *    var withDefault = ObjectBuilder.partial(fn, defaultConfig);
+   *    var config = fn.apply(new Config()).build();
+   *  }
+   * }</pre>
+   *
+   * @param fn        Function that will be applied last.
+   * @param partialFn Function that will be applied first.
+   * @return ObjectBuilder with "pre-applied" function.
+   */
   static <B extends ObjectBuilder<T>, T> Function<B, ObjectBuilder<T>> partial(Function<B, ObjectBuilder<T>> fn,
       Function<B, B> partialFn) {
     return partialFn.andThen(fn);
diff --git a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
index 0fec61e59..57107f0a2 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
@@ -14,8 +14,9 @@ final class ReuseTokenProvider implements TokenProvider {
 
   /**
    * Create new {@link ReuseTokenProvider} from another {@link TokenProvider}.
-   * Wrapping an instance ReuseTokenProvider returns that instance,
-   * so this method is safe to call with any TokenProvider.
+   * Wrapping an instance ReuseTokenProvider returns that instance if the token is
+   * {@code null}, so this method is safe to call with any TokenProvider.
+   * Otherwise a new token is obtained.
    */
   static TokenProvider wrap(Token t, TokenProvider tp) {
     if (tp instanceof ReuseTokenProvider rtp) {
@@ -32,7 +33,7 @@ static TokenProvider wrap(Token t, TokenProvider tp) {
 
   private ReuseTokenProvider(Token t, TokenProvider tp) {
     this.provider = tp;
-    this.token = token;
+    this.token = t;
   }
 
   @Override
diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index 5aab362ce..06c5c57ae 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -42,4 +42,9 @@ public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, Str
     final var provider = NimbusTokenProvider.bearerToken(oidc, token);
     return reuse(token, provider);
   }
+
+  public static TokenProvider resourceOwnerPassword(OidcConfig oidc, String username, String password) {
+    final var provider = NimbusTokenProvider.resourceOwnerPassword(oidc, username, password);
+    return reuse(null, provider);
+  }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
index 9305b7a73..5e9af5a07 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
@@ -7,7 +7,6 @@
 import com.google.gson.annotations.SerializedName;
 
 import io.weaviate.client6.v1.api.WeaviateOAuthException;
-import io.weaviate.client6.v1.internal.json.JSON;
 import io.weaviate.client6.v1.internal.rest.Endpoint;
 import io.weaviate.client6.v1.internal.rest.ExternalEndpoint;
 import io.weaviate.client6.v1.internal.rest.RestTransport;
@@ -30,7 +29,7 @@ private OidcUtils() {
       request -> request, // URL is the request body.
       requesf -> Collections.emptyMap(),
       request -> null,
-      (statusCode, response) -> JSON.deserialize(response, String.class));
+      (__, response) -> response);
 
   private static record OpenIdConfiguration(
       @SerializedName("clientId") String clientId,
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
index dae185db7..33559669e 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
@@ -1,6 +1,8 @@
 package io.weaviate.client6.v1.internal.oidc.nimbus;
 
 import com.nimbusds.oauth2.sdk.AuthorizationGrant;
+import com.nimbusds.oauth2.sdk.ResourceOwnerPasswordCredentialsGrant;
+import com.nimbusds.oauth2.sdk.auth.Secret;
 
 import io.weaviate.client6.v1.internal.TokenProvider.Token;
 
@@ -11,4 +13,8 @@ interface Flow {
   static Flow bearerToken(Token t) {
     return new BearerTokenFlow(t);
   }
+
+  static Flow resourceOwnerPassword(String username, String password) {
+    return () -> new ResourceOwnerPasswordCredentialsGrant(username, new Secret(password));
+  }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
index 779b043e7..655971edb 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
@@ -33,6 +33,10 @@ public static NimbusTokenProvider bearerToken(OidcConfig oidc, Token t) {
     return new NimbusTokenProvider(oidc, Flow.bearerToken(t));
   }
 
+  public static NimbusTokenProvider resourceOwnerPassword(OidcConfig oidc, String username, String password) {
+    return new NimbusTokenProvider(oidc, Flow.resourceOwnerPassword(username, password));
+  }
+
   private NimbusTokenProvider(OidcConfig oidc, Flow flow) {
     try {
       this.metadata = OIDCProviderMetadata.parse(oidc.providerMetadata());
@@ -50,12 +54,7 @@ private NimbusTokenProvider(OidcConfig oidc, Flow flow) {
   public Token getToken() {
     var uri = metadata.getTokenEndpointURI();
     var grant = flow.getAuthorizationGrant();
-    var request = new TokenRequest.Builder(uri, clientId, grant)
-        .scope(scope)
-        .customParameter("response_type", "code", "id_token")
-        .customParameter("response_mode", "fragment")
-        .customParameter("redirect_url", redirectUrl)
-        .build().toHTTPRequest();
+    var request = new TokenRequest(uri, clientId, grant, scope).toHTTPRequest();
 
     TokenResponse response;
     try {
@@ -67,9 +66,9 @@ public Token getToken() {
 
     if (response instanceof TokenErrorResponse err) {
       var error = err.getErrorObject();
-      throw new WeaviateOAuthException("%s %s".formatted(
-          error.getCode(),
-          error.getDescription()));
+      throw new WeaviateOAuthException("%s (code=%s)".formatted(
+          error.getDescription(),
+          error.getCode()));
     }
 
     var tokens = ((OIDCTokenResponse) response).getOIDCTokens();
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/BooleanEndpoint.java b/src/main/java/io/weaviate/client6/v1/internal/rest/BooleanEndpoint.java
index b0b20665e..4856e9c2d 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/BooleanEndpoint.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/BooleanEndpoint.java
@@ -5,6 +5,13 @@
 
 public class BooleanEndpoint<RequestT> extends EndpointBase<RequestT, Boolean> {
 
+  public static BooleanEndpoint<Void> noBody(
+      Function<Void, String> method,
+      Function<Void, String> requestUrl,
+      Function<Void, Map<String, String>> queryParameters) {
+    return new BooleanEndpoint<>(method, requestUrl, queryParameters, nullBody());
+  }
+
   public BooleanEndpoint(
       Function<RequestT, String> method,
       Function<RequestT, String> requestUrl,

From 9a07f77462ef66f5301f0fdbeb281dea895bb8ec Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 14 Aug 2025 19:34:37 +0200
Subject: [PATCH 09/31] feat: implement ClientCredentials flow

A custom HttpResponseParser handles the non-compliant
error response format that some OIDC servers (e.g. Okta)
return.

Refactored ResourceOwnerPassword flow to exchange the grant
for the access_token once and then switch to RefreshToken flow.
---
 .../java/io/weaviate/containers/Weaviate.java |  6 +-
 .../integration/OIDCSupportITest.java         | 57 +++++++++----
 .../client6/v1/api/Authorization.java         |  7 ++
 .../io/weaviate/client6/v1/api/Config.java    | 19 +++--
 .../v1/internal/ExchangeTokenProvider.java    | 17 ++++
 .../v1/internal/ReuseTokenProvider.java       |  9 +-
 .../client6/v1/internal/TokenProvider.java    | 23 ++++--
 .../client6/v1/internal/oidc/OidcUtils.java   |  1 +
 .../client6/v1/internal/oidc/nimbus/Flow.java | 27 +++++-
 .../oidc/nimbus/HttpResponseParser.java       | 82 +++++++++++++++++++
 .../oidc/nimbus/NimbusTokenProvider.java      | 37 ++++-----
 11 files changed, 227 insertions(+), 58 deletions(-)
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java

diff --git a/src/it/java/io/weaviate/containers/Weaviate.java b/src/it/java/io/weaviate/containers/Weaviate.java
index e80c62e24..31dbde035 100644
--- a/src/it/java/io/weaviate/containers/Weaviate.java
+++ b/src/it/java/io/weaviate/containers/Weaviate.java
@@ -35,15 +35,17 @@ public WeaviateClient getClient(Function<Config.Custom, ObjectBuilder<Config>> f
       start();
     }
     if (clientInstance == null) {
+      var host = getHost();
       var customFn = ObjectBuilder.partial(fn,
           conn -> conn
               .scheme("http")
-              .httpHost(getHost())
-              .grpcHost(getHost())
+              .httpHost(host)
+              .grpcHost(host)
               .httpPort(getMappedPort(8080))
               .grpcPort(getMappedPort(50051)));
       try {
         clientInstance = WeaviateClient.custom(customFn);
+        // clientInstance = WeaviateClient.local();
       } catch (Exception e) {
         throw new RuntimeException("create WeaviateClient for Weaviate container", e);
       }
diff --git a/src/it/java/io/weaviate/integration/OIDCSupportITest.java b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
index 144cec0c7..2202b205a 100644
--- a/src/it/java/io/weaviate/integration/OIDCSupportITest.java
+++ b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
@@ -13,36 +13,65 @@
 import io.weaviate.client6.v1.api.Authorization;
 import io.weaviate.containers.Weaviate;
 
+/**
+ * Test that the client can use one of the supported authorization flows to
+ * obtain a token from the OIDC provider and use it in a request to Weaviate.
+ */
 public class OIDCSupportITest extends ConcurrentTest {
+  private static final String WCS_DUMMY_CI_USER = "oidc-test-user@weaviate.io";
+  private static final String WCS_DUMMY_CI_PW = System.getenv("WCS_DUMMY_CI_PW");
+
+  /**
+   * Weaviate conatiner that users WCS-backed OIDC provider.
+   * Supports ResourceOwnerPassword and RefreshToken authentication flows.
+   */
   private static final Weaviate wcsContainer = Weaviate.custom()
       .withOIDC("wcs", "https://auth.wcs.api.weaviate.io/auth/realms/SeMI", "email", "groups")
       .build();
 
-  private static final String WCS_DUMMY_CI_USER = System.getenv("WCS_DUMMY_CI_USER");
-  private static final String WCS_DUMMY_CI_PW = System.getenv("WCS_DUMMY_CI_PW");
+  private static final String OKTA_CLIENT_ID = "0oa7e9ipdkVZRUcxo5d7";
   private static final String OKTA_CLIENT_SECRET = System.getenv("OKTA_CLIENT_SECRET");
 
+  /**
+   * Weaviate container that uses Okta's dummy OIDC provider.
+   * Supports ClientCredentials flow.
+   */
+  private static final Weaviate oktaContainer = Weaviate.custom()
+      .withOIDC(OKTA_CLIENT_ID, "https://dev-32300990.okta.com/oauth2/aus7e9kxbwYQB0eht5d7", "cid", "groups")
+      .build();
+
+  @Test
+  public void test_bearerToken() {
+    Assume.assumeTrue("WCS_DUMMY_CI_PW is not set", WCS_DUMMY_CI_PW != null);
+    Assume.assumeTrue("no internet connection", hasInternetConnection());
+  }
+
   @Test
   public void test_resourceOwnerPassword() throws IOException {
-    checkSkip();
+    Assume.assumeTrue("WCS_DUMMY_CI_PW is not set", WCS_DUMMY_CI_PW != null);
+    Assume.assumeTrue("no internet connection", hasInternetConnection());
 
     var authz = Authorization.resourceOwnerPassword(WCS_DUMMY_CI_USER, WCS_DUMMY_CI_PW, List.of("test_scope"));
-
-    try (final var client = wcsContainer.getClient(conn -> conn.authorization(authz))) {
-      Assertions.assertThat(client.isLive()).isTrue();
-    }
+    pingWeaviate(wcsContainer, authz);
   }
 
   @Test
-  public void test_bearerToken() {
-    checkSkip();
+  public void test_clientCredentials() throws IOException {
+    Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
+    Assume.assumeTrue("no internet connection", hasInternetConnection());
+
+    var authz = Authorization.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of("test_scope"));
+    pingWeaviate(oktaContainer, authz);
   }
 
-  private static void checkSkip() {
-    Assume.assumeTrue("WCS_DUMMY_CI_USER is not set", WCS_DUMMY_CI_USER != null);
-    Assume.assumeTrue("WCS_DUMMY_CI_PW is not set", WCS_DUMMY_CI_PW != null);
-    Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
-    Assume.assumeTrue("no internet connection", ping("www.google.com"));
+  private static void pingWeaviate(final Weaviate container, Authorization authz) throws IOException {
+    try (final var client = container.getClient(conn -> conn.authorization(authz))) {
+      Assertions.assertThat(client.isLive()).isTrue();
+    }
+  }
+
+  private static boolean hasInternetConnection() {
+    return ping("www.google.com");
   }
 
   private static boolean ping(String site) {
diff --git a/src/main/java/io/weaviate/client6/v1/api/Authorization.java b/src/main/java/io/weaviate/client6/v1/api/Authorization.java
index 1bfaa6671..1804d536f 100644
--- a/src/main/java/io/weaviate/client6/v1/api/Authorization.java
+++ b/src/main/java/io/weaviate/client6/v1/api/Authorization.java
@@ -27,4 +27,11 @@ public static Authorization resourceOwnerPassword(String username, String passwo
       return TokenProvider.resourceOwnerPassword(oidc, username, password);
     };
   }
+
+  public static Authorization clientCredentials(String clientId, String clientSecret, List<String> scopes) {
+    return transport -> {
+      OidcConfig oidc = OidcUtils.getConfig(transport);
+      return TokenProvider.clientCredentials(oidc, clientId, clientSecret);
+    };
+  }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/api/Config.java b/src/main/java/io/weaviate/client6/v1/api/Config.java
index 60265d63a..3cbe4684f 100644
--- a/src/main/java/io/weaviate/client6/v1/api/Config.java
+++ b/src/main/java/io/weaviate/client6/v1/api/Config.java
@@ -110,6 +110,16 @@ protected SELF trustManagerFactory(TrustManagerFactory tmf) {
       return (SELF) this;
     }
 
+    /**
+     * Set authorization method. Setting this to {@code null} or omitting
+     * will not use any authorization mechanism.
+     */
+    @SuppressWarnings("unchecked")
+    public SELF authorization(Authorization authz) {
+      this.authorization = authz;
+      return (SELF) this;
+    }
+
     /**
      * Set a single request header. The client does not support header lists,
      * so there is no equivalent {@code addHeader} to append to existing header.
@@ -291,15 +301,6 @@ public Custom grpcPort(int port) {
       return this;
     }
 
-    /**
-     * Set authorization method. Setting this to {@code null} or omitting
-     * will not use any authorization mechanism.
-     */
-    public Custom authorization(Authorization authorization) {
-      this.authorization = authorization;
-      return this;
-    }
-
     /**
      * Configure a custom TrustStore to validate third-party SSL certificates.
      *
diff --git a/src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java
new file mode 100644
index 000000000..d5d9df991
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java
@@ -0,0 +1,17 @@
+package io.weaviate.client6.v1.internal;
+
+import io.weaviate.client6.v1.internal.oidc.OidcConfig;
+
+class ExchangeTokenProvider implements TokenProvider {
+  private final TokenProvider bearer;
+
+  ExchangeTokenProvider(OidcConfig oidc, TokenProvider tp) {
+    var t = tp.getToken();
+    this.bearer = TokenProvider.bearerToken(oidc, t.accessToken(), t.refreshToken(), t.expiresIn());
+  }
+
+  @Override
+  public Token getToken() {
+    return bearer.getToken();
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
index 57107f0a2..dda566490 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
@@ -16,7 +16,6 @@ final class ReuseTokenProvider implements TokenProvider {
    * Create new {@link ReuseTokenProvider} from another {@link TokenProvider}.
    * Wrapping an instance ReuseTokenProvider returns that instance if the token is
    * {@code null}, so this method is safe to call with any TokenProvider.
-   * Otherwise a new token is obtained.
    */
   static TokenProvider wrap(Token t, TokenProvider tp) {
     if (tp instanceof ReuseTokenProvider rtp) {
@@ -24,10 +23,6 @@ static TokenProvider wrap(Token t, TokenProvider tp) {
         return rtp; // Use it directly.
       }
     }
-
-    if (t == null) {
-      t = tp.getToken();
-    }
     return new ReuseTokenProvider(t, tp);
   }
 
@@ -38,11 +33,11 @@ private ReuseTokenProvider(Token t, TokenProvider tp) {
 
   @Override
   public Token getToken() {
-    if (token.isValid()) {
+    if (token != null && token.isValid()) {
       return token;
     }
     synchronized (this) {
-      if (!token.isValid()) {
+      if (token == null || !token.isValid()) {
         token = provider.getToken();
       }
     }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index 06c5c57ae..f5bd6c429 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -22,6 +22,10 @@ public static Token expireAfter(String accessToken, String refreshToken, long ex
       return new Token(accessToken, refreshToken, Instant.now(), expiresIn);
     }
 
+    public static Token expireAfter(String accessToken, long expiresIn) {
+      return expireAfter(accessToken, null, expiresIn);
+    }
+
     /** Create a token that never expires. */
     public static Token expireNever(String accessToken) {
       return Token.expireAfter(accessToken, "", -1);
@@ -33,10 +37,6 @@ public static TokenProvider staticToken(String accessToken) {
     return () -> token;
   }
 
-  public static TokenProvider reuse(Token t, TokenProvider tp) {
-    return ReuseTokenProvider.wrap(t, tp);
-  }
-
   public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, String refreshToken, long expiresIn) {
     final var token = Token.expireAfter(accessToken, refreshToken, expiresIn);
     final var provider = NimbusTokenProvider.bearerToken(oidc, token);
@@ -44,7 +44,20 @@ public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, Str
   }
 
   public static TokenProvider resourceOwnerPassword(OidcConfig oidc, String username, String password) {
-    final var provider = NimbusTokenProvider.resourceOwnerPassword(oidc, username, password);
+    final var passwordGrant = NimbusTokenProvider.resourceOwnerPassword(oidc, username, password);
+    return reuse(null, exchange(oidc, passwordGrant));
+  }
+
+  public static TokenProvider clientCredentials(OidcConfig oidc, String clientId, String clientSecret) {
+    final var provider = NimbusTokenProvider.clientCredentials(oidc, clientId, clientSecret);
     return reuse(null, provider);
   }
+
+  static TokenProvider exchange(OidcConfig oidc, TokenProvider tp) {
+    return new ExchangeTokenProvider(oidc, tp);
+  }
+
+  static TokenProvider reuse(Token t, TokenProvider tp) {
+    return ReuseTokenProvider.wrap(t, tp);
+  }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
index 5e9af5a07..0d1969036 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
@@ -13,6 +13,7 @@
 import io.weaviate.client6.v1.internal.rest.SimpleEndpoint;
 
 public final class OidcUtils {
+  /** Prevents public initialization. */
   private OidcUtils() {
   }
 
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
index 33559669e..1fb247469 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
@@ -1,8 +1,12 @@
 package io.weaviate.client6.v1.internal.oidc.nimbus;
 
 import com.nimbusds.oauth2.sdk.AuthorizationGrant;
+import com.nimbusds.oauth2.sdk.ClientCredentialsGrant;
 import com.nimbusds.oauth2.sdk.ResourceOwnerPasswordCredentialsGrant;
+import com.nimbusds.oauth2.sdk.auth.ClientAuthentication;
+import com.nimbusds.oauth2.sdk.auth.ClientSecretPost;
 import com.nimbusds.oauth2.sdk.auth.Secret;
+import com.nimbusds.oauth2.sdk.id.ClientID;
 
 import io.weaviate.client6.v1.internal.TokenProvider.Token;
 
@@ -10,11 +14,32 @@
 interface Flow {
   AuthorizationGrant getAuthorizationGrant();
 
+  default ClientAuthentication getClientAuthentication() {
+    return null;
+  }
+
   static Flow bearerToken(Token t) {
     return new BearerTokenFlow(t);
   }
 
   static Flow resourceOwnerPassword(String username, String password) {
-    return () -> new ResourceOwnerPasswordCredentialsGrant(username, new Secret(password));
+    final var GRANT = new ResourceOwnerPasswordCredentialsGrant(username, new Secret(password));
+    return () -> GRANT; // Reuse cached authorization grant
+  }
+
+  static Flow clientCredentials(String clientId, String clientSecret) {
+    return new Flow() {
+      private static final AuthorizationGrant GRANT = new ClientCredentialsGrant();
+
+      @Override
+      public AuthorizationGrant getAuthorizationGrant() {
+        return GRANT;
+      }
+
+      @Override
+      public ClientAuthentication getClientAuthentication() {
+        return new ClientSecretPost(new ClientID(clientId), new Secret(clientSecret));
+      }
+    };
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java
new file mode 100644
index 000000000..e2d12d191
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java
@@ -0,0 +1,82 @@
+package io.weaviate.client6.v1.internal.oidc.nimbus;
+
+import com.google.gson.annotations.SerializedName;
+import com.nimbusds.oauth2.sdk.ErrorResponse;
+import com.nimbusds.oauth2.sdk.ParseException;
+import com.nimbusds.oauth2.sdk.TokenResponse;
+import com.nimbusds.oauth2.sdk.http.HTTPResponse;
+import com.nimbusds.openid.connect.sdk.OIDCTokenResponse;
+import com.nimbusds.openid.connect.sdk.OIDCTokenResponseParser;
+import com.nimbusds.openid.connect.sdk.token.OIDCTokens;
+
+import io.weaviate.client6.v1.api.WeaviateOAuthException;
+import io.weaviate.client6.v1.internal.json.JSON;
+
+final class OIDCTokensParser {
+  /**
+   * Prevents public instantiation.
+   */
+  private OIDCTokensParser() {
+  }
+
+  /**
+   * Parse HTTP response containing a new set of OIDC tokens (access_token and
+   * refresh_token).
+   *
+   * <p>
+   * Nimbus expects the following format of an error response, as per RFC 6749:
+   *
+   * <pre>
+   *  {
+   *    "error_code": "invalid_client",
+   *    "error_description": "Invalid value for 'client_id' parameter."
+   *  }
+   * </pre>
+   *
+   * Unfortunately, not all OIDC servers adhere to it. E.g. Okta returns
+   * {@code "errorCode"} and {@code "errorSummary"}, which Nimbus's
+   * {@link OIDCTokenResponseParser} fails to parse. In order to get a meaningful
+   * error message we make a second pass in case error details are incomplete
+   * after the first pass.
+   *
+   * @throws ParseException         if {@link OIDCTokenResponseParser#parse()}
+   *                                failed.
+   * @throws WeaviateOAuthException if response indicates error. As determined by
+   *                                {@link TokenResponse#indicatesSuccess()}.
+   */
+  static OIDCTokens parse(HTTPResponse httpResponse) throws ParseException {
+    var response = OIDCTokenResponseParser.parse(httpResponse);
+    if (response.indicatesSuccess()) {
+      return ((OIDCTokenResponse) response).getOIDCTokens();
+    }
+
+    var error = fromErrorResponse(response.toErrorResponse());
+    if (!error.isComplete()) {
+      var error2 = fromHttpResponse(httpResponse);
+      error = error2;
+    }
+    throw new WeaviateOAuthException("%s (code=%s)".formatted(
+        error.description(),
+        error.code()));
+  }
+
+  private static record ErrorDetails(
+      @SerializedName("errorCode") String code,
+      @SerializedName("errorSummary") String description) {
+
+    private boolean isComplete() {
+      return code != null && description != null;
+    }
+  }
+
+  private static ErrorDetails fromErrorResponse(ErrorResponse response) {
+    var err = response.getErrorObject();
+    return new ErrorDetails(err.getCode(), err.getDescription());
+  }
+
+  private static ErrorDetails fromHttpResponse(HTTPResponse response) {
+    System.out.println(response.getBody());
+    System.out.println(JSON.deserialize(response.getBody(), ErrorDetails.class));
+    return JSON.deserialize(response.getBody(), ErrorDetails.class);
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
index 655971edb..f172152e0 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
@@ -8,14 +8,11 @@
 import com.nimbusds.oauth2.sdk.ParseException;
 import com.nimbusds.oauth2.sdk.RefreshTokenGrant;
 import com.nimbusds.oauth2.sdk.Scope;
-import com.nimbusds.oauth2.sdk.TokenErrorResponse;
 import com.nimbusds.oauth2.sdk.TokenRequest;
-import com.nimbusds.oauth2.sdk.TokenResponse;
 import com.nimbusds.oauth2.sdk.id.ClientID;
 import com.nimbusds.oauth2.sdk.token.RefreshToken;
-import com.nimbusds.openid.connect.sdk.OIDCTokenResponse;
-import com.nimbusds.openid.connect.sdk.OIDCTokenResponseParser;
 import com.nimbusds.openid.connect.sdk.op.OIDCProviderMetadata;
+import com.nimbusds.openid.connect.sdk.token.OIDCTokens;
 
 import io.weaviate.client6.v1.api.WeaviateOAuthException;
 import io.weaviate.client6.v1.internal.TokenProvider;
@@ -37,6 +34,10 @@ public static NimbusTokenProvider resourceOwnerPassword(OidcConfig oidc, String
     return new NimbusTokenProvider(oidc, Flow.resourceOwnerPassword(username, password));
   }
 
+  public static NimbusTokenProvider clientCredentials(OidcConfig oidc, String clientId, String clientSecret) {
+    return new NimbusTokenProvider(oidc, Flow.clientCredentials(clientId, clientSecret));
+  }
+
   private NimbusTokenProvider(OidcConfig oidc, Flow flow) {
     try {
       this.metadata = OIDCProviderMetadata.parse(oidc.providerMetadata());
@@ -54,31 +55,27 @@ private NimbusTokenProvider(OidcConfig oidc, Flow flow) {
   public Token getToken() {
     var uri = metadata.getTokenEndpointURI();
     var grant = flow.getAuthorizationGrant();
-    var request = new TokenRequest(uri, clientId, grant, scope).toHTTPRequest();
 
-    TokenResponse response;
+    var clientAuth = flow.getClientAuthentication();
+    var tokenRequest = clientAuth == null
+        ? new TokenRequest(uri, clientId, grant, scope)
+        : new TokenRequest(uri, clientAuth, grant, scope);
+    var request = tokenRequest.toHTTPRequest();
+
+    OIDCTokens tokens;
     try {
-      var httpResponse = request.send();
-      response = OIDCTokenResponseParser.parse(httpResponse);
+      var response = request.send();
+      tokens = OIDCTokensParser.parse(response);
     } catch (IOException | ParseException e) {
       throw new WeaviateOAuthException(e);
     }
 
-    if (response instanceof TokenErrorResponse err) {
-      var error = err.getErrorObject();
-      throw new WeaviateOAuthException("%s (code=%s)".formatted(
-          error.getDescription(),
-          error.getCode()));
-    }
-
-    var tokens = ((OIDCTokenResponse) response).getOIDCTokens();
     var accessToken = tokens.getAccessToken();
     var refreshToken = tokens.getRefreshToken();
 
-    var newToken = Token.expireAfter(
-        accessToken.getValue(),
-        refreshToken.getValue(),
-        accessToken.getLifetime());
+    var newToken = refreshToken == null
+        ? Token.expireAfter(accessToken.getValue(), accessToken.getLifetime())
+        : Token.expireAfter(accessToken.getValue(), refreshToken.getValue(), accessToken.getLifetime());
 
     if (flow instanceof BearerTokenFlow btf) {
       btf.setToken(newToken);

From 1f73f0fb723431f7b886571e3c6fb68ece11fb64 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 14 Aug 2025 20:32:08 +0200
Subject: [PATCH 10/31] chore: rename bearerToken flow to refreshToken
 internally

Document public and internal APIs.
---
 .../client6/v1/api/Authorization.java         | 39 ++++++++++
 .../v1/internal/ExchangeTokenProvider.java    | 15 ++++
 .../v1/internal/ReuseTokenProvider.java       | 11 +++
 .../client6/v1/internal/TokenProvider.java    | 77 ++++++++++++++++++-
 .../client6/v1/internal/oidc/nimbus/Flow.java |  4 +-
 .../oidc/nimbus/NimbusTokenProvider.java      | 36 ++++++++-
 ...erTokenFlow.java => RefreshTokenFlow.java} | 10 ++-
 7 files changed, 183 insertions(+), 9 deletions(-)
 rename src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/{BearerTokenFlow.java => RefreshTokenFlow.java} (62%)

diff --git a/src/main/java/io/weaviate/client6/v1/api/Authorization.java b/src/main/java/io/weaviate/client6/v1/api/Authorization.java
index 1804d536f..cc3415127 100644
--- a/src/main/java/io/weaviate/client6/v1/api/Authorization.java
+++ b/src/main/java/io/weaviate/client6/v1/api/Authorization.java
@@ -10,10 +10,27 @@
 public interface Authorization {
   TokenProvider getTokenProvider(RestTransport transport);
 
+  /**
+   * Authorize using a static API key.
+   *
+   * @param apiKey Weaviate API key.
+   */
   public static Authorization apiKey(String apiKey) {
     return __ -> TokenProvider.staticToken(apiKey);
   }
 
+  /**
+   * Authorize using an existing access_token + refresh_token
+   * pair.
+   *
+   * @param accessToken  Access token.
+   * @param refreshToken Refresh token.
+   * @param expiresIn    Remaining token lifetime in seconds.
+   *
+   * @return Authorization provider.
+   * @throws WeaviateOAuthException if an error occurred at any point of the
+   *                                exchange process.
+   */
   public static Authorization bearerToken(String accessToken, String refreshToken, long expiresIn) {
     return transport -> {
       OidcConfig oidc = OidcUtils.getConfig(transport);
@@ -21,6 +38,17 @@ public static Authorization bearerToken(String accessToken, String refreshToken,
     };
   }
 
+  /**
+   * Authorize using Resource Owner Password authorization grant.
+   *
+   * @param username Resource owner username.
+   * @param password Resource owner password.
+   * @param scopes   Client scopes.
+   *
+   * @return Authorization provider.
+   * @throws WeaviateOAuthException if an error occured at any point of the token
+   *                                exchange process.
+   */
   public static Authorization resourceOwnerPassword(String username, String password, List<String> scopes) {
     return transport -> {
       OidcConfig oidc = OidcUtils.getConfig(transport);
@@ -28,6 +56,17 @@ public static Authorization resourceOwnerPassword(String username, String passwo
     };
   }
 
+  /**
+   * Authorize using Client Credentials authorization grant.
+   *
+   * @param clientId     Client ID.
+   * @param clientSecret Client secret.
+   * @param scopes       Client scopes.
+   *
+   * @return Authorization provider.
+   * @throws WeaviateOAuthException if an error occured at any point while
+   *                                obtaining a new token.
+   */
   public static Authorization clientCredentials(String clientId, String clientSecret, List<String> scopes) {
     return transport -> {
       OidcConfig oidc = OidcUtils.getConfig(transport);
diff --git a/src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java
index d5d9df991..175dd13a9 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java
@@ -2,6 +2,21 @@
 
 import io.weaviate.client6.v1.internal.oidc.OidcConfig;
 
+/**
+ * ExchangeTokenProvider obtains a new {@link Token} from "single-use"
+ * {@link TokenProvider}, usually one using an Resource Owner Password grant.
+ * It then creates a new internal TokenProvider to refresh the token each time
+ * {@link #getToken} is called.
+ *
+ * <p>
+ * Usage:
+ *
+ * <pre>{@code
+ * var initialGrant = TokenProvider.resourceOwnerPassword(oidc, username, password);
+ * var exchange = new ExchangeTokenProvider(oidc, initialGrant);
+ * var token = exchange.getToken();
+ * } </pre>
+ */
 class ExchangeTokenProvider implements TokenProvider {
   private final TokenProvider bearer;
 
diff --git a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
index dda566490..23520982e 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
@@ -5,6 +5,17 @@
 /**
  * ReuseTokenProvider returns the same token as long as its valid and obtains a
  * new token from a {@link TokenProvider} otherwise.
+ *
+ * <p>
+ * Usage:
+ *
+ * <pre>{@code
+ * // Create an TokenProvider that can rotate tokens as they expire.
+ * var myProvider = new MyTokenProvider();
+ *
+ * // Create a reusable TokenProvider.
+ * var tokenProvider = ReuseTokenProvider.wrap(myProvider);
+ * }</pre>
  */
 @ThreadSafe
 final class ReuseTokenProvider implements TokenProvider {
diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index f5bd6c429..90ce3d161 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -2,14 +2,21 @@
 
 import java.time.Instant;
 
+import io.weaviate.client6.v1.api.WeaviateOAuthException;
 import io.weaviate.client6.v1.internal.oidc.OidcConfig;
 import io.weaviate.client6.v1.internal.oidc.nimbus.NimbusTokenProvider;
 
+/** TokenProvider obtains authentication tokens. */
 @FunctionalInterface
 public interface TokenProvider {
   Token getToken();
 
+  /** Token represents an access_token + refresh_token pair. */
   public record Token(String accessToken, String refreshToken, Instant createdAt, long expiresIn) {
+    /**
+     * Returns {@code true} if remaining lifetime of the token is greater than 0.
+     * Tokens created with {@link #expireNever} are always valid.
+     */
     public boolean isValid() {
       if (expiresIn == -1) {
         return true;
@@ -18,17 +25,39 @@ public boolean isValid() {
       return Instant.now().isAfter(createdAt.plusSeconds(expiresIn));
     }
 
+    /**
+     * Create a token with an expiration and a refresh_token.
+     *
+     * @param accessToken  Access token.
+     * @param refreshToken Refresh token.
+     * @param expiresIn    Remaining token lifetime in seconds.
+     *
+     * @return A new Token.
+     */
     public static Token expireAfter(String accessToken, String refreshToken, long expiresIn) {
       return new Token(accessToken, refreshToken, Instant.now(), expiresIn);
     }
 
+    /**
+     * Create a token that does not have a refresh_token.
+     *
+     * @param accessToken Access token.
+     * @param expiresIn   Remaining token lifetime in seconds.
+     *
+     * @return A new Token.
+     */
     public static Token expireAfter(String accessToken, long expiresIn) {
       return expireAfter(accessToken, null, expiresIn);
     }
 
-    /** Create a token that never expires. */
+    /**
+     * Create a token that never expires.
+     *
+     * @param accessToken Access token.
+     * @return A new Token.
+     */
     public static Token expireNever(String accessToken) {
-      return Token.expireAfter(accessToken, "", -1);
+      return Token.expireAfter(accessToken, -1);
     }
   }
 
@@ -37,26 +66,68 @@ public static TokenProvider staticToken(String accessToken) {
     return () -> token;
   }
 
+  /**
+   * Create a TokenProvider that uses an existing access_token + refresh_token
+   * pair.
+   *
+   * @param oidc         OIDC config.
+   * @param accessToken  Access token.
+   * @param refreshToken Refresh token.
+   * @param expiresIn    Remaining token lifetime in seconds.
+   *
+   * @return Internal TokenProvider implementation.
+   * @throws WeaviateOAuthException if an error occurred at any point of the
+   *                                exchange process.
+   */
   public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, String refreshToken, long expiresIn) {
     final var token = Token.expireAfter(accessToken, refreshToken, expiresIn);
-    final var provider = NimbusTokenProvider.bearerToken(oidc, token);
+    final var provider = NimbusTokenProvider.refreshToken(oidc, token);
     return reuse(token, provider);
   }
 
+  /**
+   * Create a TokenProvider that uses Resource Owner Password authorization grant.
+   *
+   * @param oidc     OIDC config.
+   * @param username Resource owner username.
+   * @param password Resource owner password.
+   *
+   * @return Internal TokenProvider implementation.
+   * @throws WeaviateOAuthException if an error occured at any point of the token
+   *                                exchange process.
+   */
   public static TokenProvider resourceOwnerPassword(OidcConfig oidc, String username, String password) {
     final var passwordGrant = NimbusTokenProvider.resourceOwnerPassword(oidc, username, password);
     return reuse(null, exchange(oidc, passwordGrant));
   }
 
+  /**
+   * Create a TokenProvider that uses Client Credentials authorization grant.
+   *
+   * @param oidc         OIDC config.
+   * @param clientId     Client ID.
+   * @param clientSecret Client secret.
+   *
+   * @return Internal TokenProvider implementation.
+   * @throws WeaviateOAuthException if an error occured at any point while
+   *                                obtaining a new token.
+   */
   public static TokenProvider clientCredentials(OidcConfig oidc, String clientId, String clientSecret) {
     final var provider = NimbusTokenProvider.clientCredentials(oidc, clientId, clientSecret);
     return reuse(null, provider);
   }
 
+  /**
+   * Obtain a TokenProvider that exchanges an authorization grant for a new Token.
+   */
   static TokenProvider exchange(OidcConfig oidc, TokenProvider tp) {
     return new ExchangeTokenProvider(oidc, tp);
   }
 
+  /**
+   * Obtain a TokenProvider which reuses tokens obtained
+   * from another TokenProvider until they expire.
+   */
   static TokenProvider reuse(Token t, TokenProvider tp) {
     return ReuseTokenProvider.wrap(t, tp);
   }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
index 1fb247469..ca91361b5 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
@@ -18,8 +18,8 @@ default ClientAuthentication getClientAuthentication() {
     return null;
   }
 
-  static Flow bearerToken(Token t) {
-    return new BearerTokenFlow(t);
+  static Flow refreshToken(Token t) {
+    return new RefreshTokenFlow(t);
   }
 
   static Flow resourceOwnerPassword(String username, String password) {
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
index f172152e0..199e2678d 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
@@ -26,14 +26,46 @@ public final class NimbusTokenProvider implements TokenProvider {
   private final String redirectUrl;
   private final Flow flow;
 
-  public static NimbusTokenProvider bearerToken(OidcConfig oidc, Token t) {
-    return new NimbusTokenProvider(oidc, Flow.bearerToken(t));
+  /**
+   * Create a TokenProvider that uses Refresh Token authorization grant.
+   *
+   * @param oidc OIDC config.
+   * @param t    Current token. Must not be null.
+   *
+   * @return A new instance of NimbusTokenProvider. Instances are never cached.
+   * @throws WeaviateOAuthException if an error occurred at any point of the
+   *                                exchange process.
+   */
+  public static NimbusTokenProvider refreshToken(OidcConfig oidc, Token t) {
+    return new NimbusTokenProvider(oidc, Flow.refreshToken(t));
   }
 
+  /**
+   * Create a TokenProvider that uses Resource Owner Password authorization grant.
+   *
+   * @param oidc     OIDC config.
+   * @param username Resource owner username.
+   * @param password Resource owner password.
+   *
+   * @return A new instance of NimbusTokenProvider. Instances are never cached.
+   * @throws WeaviateOAuthException if an error occured at any point of the
+   *                                exchange process.
+   */
   public static NimbusTokenProvider resourceOwnerPassword(OidcConfig oidc, String username, String password) {
     return new NimbusTokenProvider(oidc, Flow.resourceOwnerPassword(username, password));
   }
 
+  /**
+   * Create a TokenProvider that uses Client Credentials authorization grant.
+   *
+   * @param oidc         OIDC config.
+   * @param clientId     Client ID.
+   * @param clientSecret Client secret.
+   *
+   * @return A new instance of NimbusTokenProvider. Instances are never cached.
+   * @throws WeaviateOAuthException if an error occured at any point of the
+   *                                exchange process.
+   */
   public static NimbusTokenProvider clientCredentials(OidcConfig oidc, String clientId, String clientSecret) {
     return new NimbusTokenProvider(oidc, Flow.clientCredentials(clientId, clientSecret));
   }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/BearerTokenFlow.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/RefreshTokenFlow.java
similarity index 62%
rename from src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/BearerTokenFlow.java
rename to src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/RefreshTokenFlow.java
index 98904c6ae..afb1ee1bf 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/BearerTokenFlow.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/RefreshTokenFlow.java
@@ -8,11 +8,17 @@
 
 import io.weaviate.client6.v1.internal.TokenProvider.Token;
 
+/**
+ * RefreshTokenFlow provides {@link RefreshTokenGrant} with a refresh_token.
+ * Once the caller has obtained a new {@link Token} it must be updated using
+ * {@link #setToken} to ensure RefreshTokenFlow continues to return valid
+ * authorization grants.
+ */
 @NotThreadSafe
-final class BearerTokenFlow implements Flow {
+final class RefreshTokenFlow implements Flow {
   private Token t;
 
-  BearerTokenFlow(Token t) {
+  RefreshTokenFlow(Token t) {
     this.t = t;
   }
 

From 78cd310f8f98c16c00ec7bb319d81b2109d01e52 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 14 Aug 2025 20:36:18 +0200
Subject: [PATCH 11/31] refactor: drop unused configuration

redirect_uri is set in the old Java client but it's
nowhere to be found Python and TS clients.

Also tests show that it's not required for exchanging tokens
---
 .../io/weaviate/client6/v1/internal/oidc/OidcConfig.java  | 4 +---
 .../io/weaviate/client6/v1/internal/oidc/OidcUtils.java   | 8 +++-----
 .../v1/internal/oidc/nimbus/NimbusTokenProvider.java      | 2 --
 3 files changed, 4 insertions(+), 10 deletions(-)

diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java
index 48e7ed9fd..7caf3f06e 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java
@@ -5,13 +5,11 @@
 
 public record OidcConfig(
     String clientId,
-    String redirectUrl,
     String providerMetadata,
     List<String> scopes) {
 
-  public OidcConfig(String clientId, String redirectUrl, String providerMetadata, List<String> scopes) {
+  public OidcConfig(String clientId, String providerMetadata, List<String> scopes) {
     this.clientId = clientId;
-    this.redirectUrl = redirectUrl;
     this.providerMetadata = providerMetadata;
     this.scopes = scopes != null ? scopes : Collections.emptyList();
   }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
index 0d1969036..6ca719579 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
@@ -17,11 +17,11 @@ public final class OidcUtils {
   private OidcUtils() {
   }
 
-  private static final String OPENID_URL = "/.well-known/openid-configuration";
+  private static final String OPENID_CONFIGURATION_URL = "/.well-known/openid-configuration";
 
   private static final Endpoint<Void, OpenIdConfiguration> GET_OPENID_ENDPOINT = SimpleEndpoint.noBody(
       request -> "GET",
-      request -> "/.well-known/openid-configuration",
+      request -> OPENID_CONFIGURATION_URL,
       request -> Collections.emptyMap(),
       OpenIdConfiguration.class);
 
@@ -53,8 +53,6 @@ public static final OidcConfig getConfig(RestTransport transport) {
     } catch (IOException e) {
       throw new WeaviateOAuthException("fetch provider metadata", e);
     }
-
-    var redirectUrl = transport.getTransportOptions().baseUrl() + OPENID_URL;
-    return new OidcConfig(openid.clientId(), redirectUrl, providerMetadata, openid.scopes());
+    return new OidcConfig(openid.clientId(), providerMetadata, openid.scopes());
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
index 199e2678d..27d28f6c0 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
@@ -23,7 +23,6 @@ public final class NimbusTokenProvider implements TokenProvider {
   private final OIDCProviderMetadata metadata;
   private final ClientID clientId;
   private final Scope scope;
-  private final String redirectUrl;
   private final Flow flow;
 
   /**
@@ -79,7 +78,6 @@ private NimbusTokenProvider(OidcConfig oidc, Flow flow) {
 
     this.clientId = new ClientID(oidc.clientId());
     this.scope = new Scope(oidc.scopes().toArray(String[]::new));
-    this.redirectUrl = oidc.redirectUrl();
     this.flow = flow;
   }
 

From 01e58eae1072b492fefc5d8ecb6118c9256f6ffd Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 14 Aug 2025 22:33:14 +0200
Subject: [PATCH 12/31] feat: add user / default scopes

---
 .../integration/OIDCSupportITest.java         | 10 ++++---
 .../client6/v1/api/Authorization.java         |  7 +++--
 .../client6/v1/internal/TokenProvider.java    | 18 +++++++++++++
 .../client6/v1/internal/oidc/OidcConfig.java  | 26 ++++++++++++++++---
 .../client6/v1/internal/oidc/OidcUtils.java   |  1 +
 .../oidc/nimbus/NimbusTokenProvider.java      | 20 +++++++++-----
 6 files changed, 68 insertions(+), 14 deletions(-)

diff --git a/src/it/java/io/weaviate/integration/OIDCSupportITest.java b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
index 2202b205a..77d1d0b94 100644
--- a/src/it/java/io/weaviate/integration/OIDCSupportITest.java
+++ b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
@@ -16,9 +16,13 @@
 /**
  * Test that the client can use one of the supported authorization flows to
  * obtain a token from the OIDC provider and use it in a request to Weaviate.
+ *
+ * Running this test suite successfully requires talking to external services,
+ * so tests will be skipped if the don't have internet. See
+ * {@link #hasInternetConnection}.
  */
 public class OIDCSupportITest extends ConcurrentTest {
-  private static final String WCS_DUMMY_CI_USER = "oidc-test-user@weaviate.io";
+  private static final String WCS_DUMMY_CI_USERNAME = "oidc-test-user@weaviate.io";
   private static final String WCS_DUMMY_CI_PW = System.getenv("WCS_DUMMY_CI_PW");
 
   /**
@@ -51,7 +55,7 @@ public void test_resourceOwnerPassword() throws IOException {
     Assume.assumeTrue("WCS_DUMMY_CI_PW is not set", WCS_DUMMY_CI_PW != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
-    var authz = Authorization.resourceOwnerPassword(WCS_DUMMY_CI_USER, WCS_DUMMY_CI_PW, List.of("test_scope"));
+    var authz = Authorization.resourceOwnerPassword(WCS_DUMMY_CI_USERNAME, WCS_DUMMY_CI_PW, List.of());
     pingWeaviate(wcsContainer, authz);
   }
 
@@ -60,7 +64,7 @@ public void test_clientCredentials() throws IOException {
     Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
-    var authz = Authorization.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of("test_scope"));
+    var authz = Authorization.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
     pingWeaviate(oktaContainer, authz);
   }
 
diff --git a/src/main/java/io/weaviate/client6/v1/api/Authorization.java b/src/main/java/io/weaviate/client6/v1/api/Authorization.java
index cc3415127..329d655d0 100644
--- a/src/main/java/io/weaviate/client6/v1/api/Authorization.java
+++ b/src/main/java/io/weaviate/client6/v1/api/Authorization.java
@@ -51,7 +51,7 @@ public static Authorization bearerToken(String accessToken, String refreshToken,
    */
   public static Authorization resourceOwnerPassword(String username, String password, List<String> scopes) {
     return transport -> {
-      OidcConfig oidc = OidcUtils.getConfig(transport);
+      OidcConfig oidc = OidcUtils.getConfig(transport).withScopes(scopes).withScopes("offline_access");
       return TokenProvider.resourceOwnerPassword(oidc, username, password);
     };
   }
@@ -69,7 +69,10 @@ public static Authorization resourceOwnerPassword(String username, String passwo
    */
   public static Authorization clientCredentials(String clientId, String clientSecret, List<String> scopes) {
     return transport -> {
-      OidcConfig oidc = OidcUtils.getConfig(transport);
+      OidcConfig oidc = OidcUtils.getConfig(transport).withScopes(scopes);
+      if (oidc.scopes().isEmpty() && TokenProvider.isMicrosoft(oidc)) {
+        oidc = oidc.withScopes(clientId + "/.default");
+      }
       return TokenProvider.clientCredentials(oidc, clientId, clientSecret);
     };
   }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index 90ce3d161..ad19ba893 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -1,5 +1,6 @@
 package io.weaviate.client6.v1.internal;
 
+import java.net.URI;
 import java.time.Instant;
 
 import io.weaviate.client6.v1.api.WeaviateOAuthException;
@@ -131,4 +132,21 @@ static TokenProvider exchange(OidcConfig oidc, TokenProvider tp) {
   static TokenProvider reuse(Token t, TokenProvider tp) {
     return ReuseTokenProvider.wrap(t, tp);
   }
+
+  public record ProviderMetadata(URI tokenEndpoint) {
+  }
+
+  /**
+   * Returns true if this OIDC provider's token endpoint is hosted at
+   * {@code login.microsoftonline.com}.
+   *
+   * @param oidc OIDC config.
+   *
+   * @throws WeaviateOAuthException if metadata could not be parsed.
+   */
+  public static boolean isMicrosoft(OidcConfig oidc) {
+    var metadata = NimbusTokenProvider.parseProviderMetadata(oidc.providerMetadata());
+    return metadata.tokenEndpoint().getHost().contains("login.microsoftonline.com");
+  }
+
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java
index 7caf3f06e..858fd4d82 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcConfig.java
@@ -1,16 +1,36 @@
 package io.weaviate.client6.v1.internal.oidc;
 
+import java.util.Arrays;
 import java.util.Collections;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
 public record OidcConfig(
     String clientId,
     String providerMetadata,
-    List<String> scopes) {
+    Set<String> scopes) {
 
-  public OidcConfig(String clientId, String providerMetadata, List<String> scopes) {
+  public OidcConfig(String clientId, String providerMetadata, Set<String> scopes) {
     this.clientId = clientId;
     this.providerMetadata = providerMetadata;
-    this.scopes = scopes != null ? scopes : Collections.emptyList();
+    this.scopes = scopes != null ? Set.copyOf(scopes) : Collections.emptySet();
+  }
+
+  public OidcConfig(String clientId, String providerMetadata, List<String> scopes) {
+    this(clientId, providerMetadata, scopes == null ? null : new HashSet<>(scopes));
+  }
+
+  /** Create a new OIDC config with extended scopes. */
+  public OidcConfig withScopes(String... scopes) {
+    return withScopes(Arrays.asList(scopes));
+  }
+
+  /** Create a new OIDC config with extended scopes. */
+  public OidcConfig withScopes(List<String> scopes) {
+    var newScopes = Stream.concat(this.scopes.stream(), scopes.stream()).collect(Collectors.toSet());
+    return new OidcConfig(clientId, providerMetadata, newScopes);
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
index 6ca719579..cafcc1289 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/OidcUtils.java
@@ -53,6 +53,7 @@ public static final OidcConfig getConfig(RestTransport transport) {
     } catch (IOException e) {
       throw new WeaviateOAuthException("fetch provider metadata", e);
     }
+
     return new OidcConfig(openid.clientId(), providerMetadata, openid.scopes());
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
index 27d28f6c0..3437159c7 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
@@ -70,12 +70,7 @@ public static NimbusTokenProvider clientCredentials(OidcConfig oidc, String clie
   }
 
   private NimbusTokenProvider(OidcConfig oidc, Flow flow) {
-    try {
-      this.metadata = OIDCProviderMetadata.parse(oidc.providerMetadata());
-    } catch (ParseException ex) {
-      throw new WeaviateOAuthException("parse provider metadata: ", ex);
-    }
-
+    this.metadata = _parseProviderMetadata(oidc.providerMetadata());
     this.clientId = new ClientID(oidc.clientId());
     this.scope = new Scope(oidc.scopes().toArray(String[]::new));
     this.flow = flow;
@@ -114,6 +109,19 @@ public Token getToken() {
     return newToken;
   }
 
+  public static ProviderMetadata parseProviderMetadata(String providerMetadata) {
+    var metadata = _parseProviderMetadata(providerMetadata);
+    return new ProviderMetadata(metadata.getTokenEndpointURI());
+  }
+
+  private static OIDCProviderMetadata _parseProviderMetadata(String providerMetadata) {
+    try {
+      return OIDCProviderMetadata.parse(providerMetadata);
+    } catch (ParseException ex) {
+      throw new WeaviateOAuthException("parse provider metadata: ", ex);
+    }
+  }
+
   @NotThreadSafe
   final class BearerTokenFlow implements Flow {
     private Token t;

From 6bd8056e478e02f6a43ce57b689c4508d06f3af4 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 14 Aug 2025 23:24:48 +0200
Subject: [PATCH 13/31] test: finish Bearer Token test case

Deleted NimbusTokenProvider.BearerTokenFlow class, no longer used.
Added a wrapper for WeaviateClient that can tie client's lifetime
to that of the Testcontainer that created it. That way the client,
once opened, is only closed when the container it belonged to is stopped.
---
 .../io/weaviate/containers/Container.java     | 10 ---
 .../java/io/weaviate/containers/Weaviate.java | 69 +++++++++++++------
 .../integration/OIDCSupportITest.java         | 37 +++++++++-
 .../oidc/nimbus/HttpResponseParser.java       |  2 -
 .../oidc/nimbus/NimbusTokenProvider.java      | 25 +------
 5 files changed, 86 insertions(+), 57 deletions(-)

diff --git a/src/it/java/io/weaviate/containers/Container.java b/src/it/java/io/weaviate/containers/Container.java
index 4a95b4044..e3d9d82fd 100644
--- a/src/it/java/io/weaviate/containers/Container.java
+++ b/src/it/java/io/weaviate/containers/Container.java
@@ -17,16 +17,6 @@ public class Container {
   public static final Contextionary CONTEXTIONARY = Contextionary.createDefault();
   public static final Img2VecNeural IMG2VEC_NEURAL = Img2VecNeural.createDefault();
 
-  static {
-    startAll();
-  }
-
-  /** Start all shared Testcontainers. */
-  // TODO: start lazily!
-  static void startAll() {
-    // WEAVIATE.start();
-  }
-
   /**
    * Stop all shared Testcontainers created in {@link #startAll}.
    * <p>
diff --git a/src/it/java/io/weaviate/containers/Weaviate.java b/src/it/java/io/weaviate/containers/Weaviate.java
index 31dbde035..bd166c745 100644
--- a/src/it/java/io/weaviate/containers/Weaviate.java
+++ b/src/it/java/io/weaviate/containers/Weaviate.java
@@ -15,11 +15,11 @@
 import io.weaviate.client6.v1.internal.ObjectBuilder;
 
 public class Weaviate extends WeaviateContainer {
-  private WeaviateClient clientInstance;
-
   public static final String VERSION = "1.29.1";
   public static final String DOCKER_IMAGE = "semitechnologies/weaviate";
 
+  private volatile SharedClient clientInstance;
+
   public WeaviateClient getClient() {
     return getClient(ObjectBuilder.identity());
   }
@@ -30,24 +30,29 @@ public WeaviateClient getClient() {
    * this is not made thread-safe.
    */
   public WeaviateClient getClient(Function<Config.Custom, ObjectBuilder<Config>> fn) {
-    // FIXME: control from containers?
     if (!isRunning()) {
       start();
     }
-    if (clientInstance == null) {
-      var host = getHost();
-      var customFn = ObjectBuilder.partial(fn,
-          conn -> conn
-              .scheme("http")
-              .httpHost(host)
-              .grpcHost(host)
-              .httpPort(getMappedPort(8080))
-              .grpcPort(getMappedPort(50051)));
-      try {
-        clientInstance = WeaviateClient.custom(customFn);
-        // clientInstance = WeaviateClient.local();
-      } catch (Exception e) {
-        throw new RuntimeException("create WeaviateClient for Weaviate container", e);
+    if (clientInstance != null) {
+      return clientInstance;
+    }
+
+    synchronized (this) {
+      if (clientInstance == null) {
+        var host = getHost();
+        var customFn = ObjectBuilder.partial(fn,
+            conn -> conn
+                .scheme("http")
+                .httpHost(host)
+                .grpcHost(host)
+                .httpPort(getMappedPort(8080))
+                .grpcPort(getMappedPort(50051)));
+        var config = customFn.apply(new Config.Custom()).build();
+        try {
+          clientInstance = new SharedClient(config, this);
+        } catch (Exception e) {
+          throw new RuntimeException("create WeaviateClient for Weaviate container", e);
+        }
       }
     }
     return clientInstance;
@@ -149,10 +154,32 @@ public void stop() {
     if (clientInstance == null) {
       return;
     }
-    try {
-      clientInstance.close();
-    } catch (IOException e) {
-      // TODO: log error
+    synchronized (this) {
+      try {
+        clientInstance.close(this);
+      } catch (IOException e) {
+        throw new RuntimeException(e);
+      }
+    }
+  }
+
+  /** SharedClient's lifetime is tied to that of it's parent container. */
+  private class SharedClient extends WeaviateClient {
+    private final Weaviate parent;
+
+    private SharedClient(Config config, Weaviate parent) {
+      super(config);
+      this.parent = parent;
+    }
+
+    private void close(Weaviate caller) throws IOException {
+      if (caller == parent) {
+        super.close();
+      }
+    }
+
+    @Override
+    public void close() throws IOException {
     }
   }
 }
diff --git a/src/it/java/io/weaviate/integration/OIDCSupportITest.java b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
index 77d1d0b94..5d9921910 100644
--- a/src/it/java/io/weaviate/integration/OIDCSupportITest.java
+++ b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
@@ -11,6 +11,8 @@
 
 import io.weaviate.ConcurrentTest;
 import io.weaviate.client6.v1.api.Authorization;
+import io.weaviate.client6.v1.internal.TokenProvider;
+import io.weaviate.client6.v1.internal.rest.RestTransport;
 import io.weaviate.containers.Weaviate;
 
 /**
@@ -45,9 +47,13 @@ public class OIDCSupportITest extends ConcurrentTest {
       .build();
 
   @Test
-  public void test_bearerToken() {
+  public void test_bearerToken() throws IOException {
     Assume.assumeTrue("WCS_DUMMY_CI_PW is not set", WCS_DUMMY_CI_PW != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
+
+    var t = TokenInterceptor.stealToken();
+    var authz = Authorization.bearerToken(t.accessToken(), t.refreshToken(), t.expiresIn());
+    pingWeaviate(wcsContainer, authz);
   }
 
   @Test
@@ -66,6 +72,7 @@ public void test_clientCredentials() throws IOException {
 
     var authz = Authorization.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
     pingWeaviate(oktaContainer, authz);
+    pingWeaviate(oktaContainer, authz);
   }
 
   private static void pingWeaviate(final Weaviate container, Authorization authz) throws IOException {
@@ -87,4 +94,32 @@ private static boolean ping(String site) {
       return false;
     }
   }
+
+  private static class TokenInterceptor implements Authorization, TokenProvider {
+    /** Exchange resource owner password for a token and return it. */
+    public static Token stealToken() throws IOException {
+      var authz = Authorization.resourceOwnerPassword(WCS_DUMMY_CI_USERNAME, WCS_DUMMY_CI_PW, List.of());
+      var spy = new TokenInterceptor(authz);
+      pingWeaviate(wcsContainer, spy);
+      return spy.getToken();
+    }
+
+    private Authorization authorization;
+    private TokenProvider tokenProvider;
+
+    private TokenInterceptor(Authorization actual) {
+      this.authorization = actual;
+    }
+
+    @Override
+    public TokenProvider getTokenProvider(RestTransport transport) {
+      tokenProvider = authorization.getTokenProvider(transport);
+      return this;
+    }
+
+    @Override
+    public Token getToken() {
+      return tokenProvider.getToken();
+    }
+  }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java
index e2d12d191..e48e13402 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java
@@ -75,8 +75,6 @@ private static ErrorDetails fromErrorResponse(ErrorResponse response) {
   }
 
   private static ErrorDetails fromHttpResponse(HTTPResponse response) {
-    System.out.println(response.getBody());
-    System.out.println(JSON.deserialize(response.getBody(), ErrorDetails.class));
     return JSON.deserialize(response.getBody(), ErrorDetails.class);
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
index 3437159c7..148264aa1 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
@@ -4,13 +4,10 @@
 
 import javax.annotation.concurrent.NotThreadSafe;
 
-import com.nimbusds.oauth2.sdk.AuthorizationGrant;
 import com.nimbusds.oauth2.sdk.ParseException;
-import com.nimbusds.oauth2.sdk.RefreshTokenGrant;
 import com.nimbusds.oauth2.sdk.Scope;
 import com.nimbusds.oauth2.sdk.TokenRequest;
 import com.nimbusds.oauth2.sdk.id.ClientID;
-import com.nimbusds.oauth2.sdk.token.RefreshToken;
 import com.nimbusds.openid.connect.sdk.op.OIDCProviderMetadata;
 import com.nimbusds.openid.connect.sdk.token.OIDCTokens;
 
@@ -102,8 +99,8 @@ public Token getToken() {
         ? Token.expireAfter(accessToken.getValue(), accessToken.getLifetime())
         : Token.expireAfter(accessToken.getValue(), refreshToken.getValue(), accessToken.getLifetime());
 
-    if (flow instanceof BearerTokenFlow btf) {
-      btf.setToken(newToken);
+    if (flow instanceof RefreshTokenFlow rtf) {
+      rtf.setToken(newToken);
     }
 
     return newToken;
@@ -121,22 +118,4 @@ private static OIDCProviderMetadata _parseProviderMetadata(String providerMetada
       throw new WeaviateOAuthException("parse provider metadata: ", ex);
     }
   }
-
-  @NotThreadSafe
-  final class BearerTokenFlow implements Flow {
-    private Token t;
-
-    BearerTokenFlow(Token t) {
-      this.t = t;
-    }
-
-    @Override
-    public AuthorizationGrant getAuthorizationGrant() {
-      return new RefreshTokenGrant(new RefreshToken(t.refreshToken()));
-    }
-
-    public void setToken(Token t) {
-      this.t = t;
-    }
-  }
 }

From 23d149a278fb1a3e011d6b15fe0f3b4624a1db09 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Fri, 15 Aug 2025 00:10:25 +0200
Subject: [PATCH 14/31] feat: add early expiry to tokens

Refreshing the token slightly ahead of its expiry
can help prevent phony unauthorized access errors.
---
 .../v1/internal/ReuseTokenProvider.java       | 34 +++++++++++--
 .../client6/v1/internal/TokenProvider.java    | 51 ++++++++++++++++---
 .../client6/v1/internal/TokenTest.java        | 36 +++++++++++++
 3 files changed, 111 insertions(+), 10 deletions(-)
 create mode 100644 src/test/java/io/weaviate/client6/v1/internal/TokenTest.java

diff --git a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
index 23520982e..594b0cad9 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
@@ -20,9 +20,25 @@
 @ThreadSafe
 final class ReuseTokenProvider implements TokenProvider {
   private final TokenProvider provider;
+  private final long expiryDelta;
 
   private volatile Token token;
 
+  /**
+   * Create new {@link ReuseTokenProvider} from another {@link TokenProvider}.
+   * Wrapping an instance ReuseTokenProvider returns that instance if the token is
+   * {@code null}, so this method is safe to call with any TokenProvider.
+   */
+  static TokenProvider wrap(Token t, TokenProvider tp, long expiryDelta) {
+    if (tp instanceof ReuseTokenProvider rtp) {
+      if (t == null) {
+        // Use it directly, but set new expirty delta.
+        return rtp.withExpiryDelta(expiryDelta);
+      }
+    }
+    return new ReuseTokenProvider(t, tp, expiryDelta);
+  }
+
   /**
    * Create new {@link ReuseTokenProvider} from another {@link TokenProvider}.
    * Wrapping an instance ReuseTokenProvider returns that instance if the token is
@@ -34,12 +50,24 @@ static TokenProvider wrap(Token t, TokenProvider tp) {
         return rtp; // Use it directly.
       }
     }
-    return new ReuseTokenProvider(t, tp);
+    return new ReuseTokenProvider(t, tp, 0);
+  }
+
+  /**
+   * Create a new TokenProvider with a different expiryDelta.
+   * Tokens obtained from this TokenProvider with have the same early expiry.
+   *
+   * @param expiryDelta Early expiry in seconds.
+   * @return A new TokenProvider.
+   */
+  TokenProvider withExpiryDelta(long expirtyDelta) {
+    return new ReuseTokenProvider(this.token, this.provider, expirtyDelta);
   }
 
-  private ReuseTokenProvider(Token t, TokenProvider tp) {
+  private ReuseTokenProvider(Token t, TokenProvider tp, long expiryDelta) {
     this.provider = tp;
     this.token = t;
+    this.expiryDelta = expiryDelta;
   }
 
   @Override
@@ -49,7 +77,7 @@ public Token getToken() {
     }
     synchronized (this) {
       if (token == null || !token.isValid()) {
-        token = provider.getToken();
+        token = provider.getToken().withExpiryDelta(expiryDelta);
       }
     }
     return token;
diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index ad19ba893..91ccd1584 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -13,7 +13,7 @@ public interface TokenProvider {
   Token getToken();
 
   /** Token represents an access_token + refresh_token pair. */
-  public record Token(String accessToken, String refreshToken, Instant createdAt, long expiresIn) {
+  public record Token(String accessToken, String refreshToken, Instant createdAt, long expiresIn, long expiryDelta) {
     /**
      * Returns {@code true} if remaining lifetime of the token is greater than 0.
      * Tokens created with {@link #expireNever} are always valid.
@@ -22,8 +22,21 @@ public boolean isValid() {
       if (expiresIn == -1) {
         return true;
       }
-      // TODO: adjust for expireDelta
-      return Instant.now().isAfter(createdAt.plusSeconds(expiresIn));
+      return Instant.now().isBefore(createdAt.plusSeconds(expiresIn - expiryDelta));
+    }
+
+    /**
+     * Set early expiry for the Token.
+     *
+     * <p>
+     * A Token with {@link #expiresIn} of 10s and {@link #expiryDelta} of 3s
+     * will be invalid 7s after being created.
+     *
+     * @param expiryDelta Early expiry in seconds.
+     * @return A Token identical to the source one, but with a different expiry.
+     */
+    public Token withExpiryDelta(long expiryDelta) {
+      return new Token(accessToken, refreshToken, createdAt, expiresIn, expiryDelta);
     }
 
     /**
@@ -36,11 +49,13 @@ public boolean isValid() {
      * @return A new Token.
      */
     public static Token expireAfter(String accessToken, String refreshToken, long expiresIn) {
-      return new Token(accessToken, refreshToken, Instant.now(), expiresIn);
+      return new Token(accessToken, refreshToken, Instant.now(), expiresIn, 0);
     }
 
     /**
      * Create a token that does not have a refresh_token.
+     * For example, a token obtained via a Client Credentials grant
+     * can only be renewed using that grant type.
      *
      * @param accessToken Access token.
      * @param expiresIn   Remaining token lifetime in seconds.
@@ -62,6 +77,20 @@ public static Token expireNever(String accessToken) {
     }
   }
 
+  /**
+   * Refreshing the token slightly ahead of time will help prevent
+   * phony unauthorized access errors.
+   *
+   * This value is currently not configuratble and should be seen
+   * as an internal implementation detail.
+   */
+  static long DEFAULT_EARLY_EXPIRY = 30;
+
+  /**
+   * Authorize using a token that never expires and doesn't need to be refreshed.
+   *
+   * @param apiKey Access token.
+   */
   public static TokenProvider staticToken(String accessToken) {
     final var token = Token.expireNever(accessToken);
     return () -> token;
@@ -83,7 +112,7 @@ public static TokenProvider staticToken(String accessToken) {
   public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, String refreshToken, long expiresIn) {
     final var token = Token.expireAfter(accessToken, refreshToken, expiresIn);
     final var provider = NimbusTokenProvider.refreshToken(oidc, token);
-    return reuse(token, provider);
+    return reuse(token, provider, DEFAULT_EARLY_EXPIRY);
   }
 
   /**
@@ -99,7 +128,7 @@ public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, Str
    */
   public static TokenProvider resourceOwnerPassword(OidcConfig oidc, String username, String password) {
     final var passwordGrant = NimbusTokenProvider.resourceOwnerPassword(oidc, username, password);
-    return reuse(null, exchange(oidc, passwordGrant));
+    return reuse(null, exchange(oidc, passwordGrant), DEFAULT_EARLY_EXPIRY);
   }
 
   /**
@@ -115,7 +144,7 @@ public static TokenProvider resourceOwnerPassword(OidcConfig oidc, String userna
    */
   public static TokenProvider clientCredentials(OidcConfig oidc, String clientId, String clientSecret) {
     final var provider = NimbusTokenProvider.clientCredentials(oidc, clientId, clientSecret);
-    return reuse(null, provider);
+    return reuse(null, provider, DEFAULT_EARLY_EXPIRY);
   }
 
   /**
@@ -133,6 +162,14 @@ static TokenProvider reuse(Token t, TokenProvider tp) {
     return ReuseTokenProvider.wrap(t, tp);
   }
 
+  /**
+   * Obtain a TokenProvider which reuses tokens obtained
+   * from another TokenProvider until they expire.
+   */
+  static TokenProvider reuse(Token t, TokenProvider tp, long expiryDelta) {
+    return ReuseTokenProvider.wrap(t, tp, expiryDelta);
+  }
+
   public record ProviderMetadata(URI tokenEndpoint) {
   }
 
diff --git a/src/test/java/io/weaviate/client6/v1/internal/TokenTest.java b/src/test/java/io/weaviate/client6/v1/internal/TokenTest.java
new file mode 100644
index 000000000..dd6cd7974
--- /dev/null
+++ b/src/test/java/io/weaviate/client6/v1/internal/TokenTest.java
@@ -0,0 +1,36 @@
+package io.weaviate.client6.v1.internal;
+
+import java.time.Instant;
+
+import org.assertj.core.api.Assertions;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import com.jparams.junit4.JParamsTestRunner;
+import com.jparams.junit4.data.DataMethod;
+
+import io.weaviate.client6.v1.internal.TokenProvider.Token;
+
+@RunWith(JParamsTestRunner.class)
+public class TokenTest {
+
+  public static Object[][] testCaseTokens() {
+    return new Object[][] {
+        { Token.expireNever("access_token"), true },
+        { Token.expireAfter("access_token", "refresh_token", 100), true },
+        { Token.expireAfter("access_token", 100), true },
+        { new Token("access_token", "refresh_token", Instant.now().minusSeconds(10), 5, 0), false },
+        { Token.expireAfter("access_token", 0), false },
+        { Token.expireAfter("access_token", 5).withExpiryDelta(10), false },
+        { Token.expireAfter("access_token", 100).withExpiryDelta(10), true },
+    };
+  }
+
+  @DataMethod(source = TokenTest.class, method = "testCaseTokens")
+  @Test
+  public void test_isValid(Token token, boolean wantValid) {
+    Assertions.assertThat(token.isValid())
+        .as(token.toString())
+        .isEqualTo(wantValid);
+  }
+}

From badbe9e24cc12abfe07dc688011be89541f04d53 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Fri, 15 Aug 2025 00:34:03 +0200
Subject: [PATCH 15/31] chore: fix javadoc

---
 .../java/io/weaviate/client6/v1/internal/TokenProvider.java     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index 91ccd1584..9b5a0e4fb 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -89,7 +89,7 @@ public static Token expireNever(String accessToken) {
   /**
    * Authorize using a token that never expires and doesn't need to be refreshed.
    *
-   * @param apiKey Access token.
+   * @param accessToken Access token.
    */
   public static TokenProvider staticToken(String accessToken) {
     final var token = Token.expireNever(accessToken);

From eb5607fa55dd6493fee15e837fa79fc6e5237550 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Fri, 15 Aug 2025 00:36:04 +0200
Subject: [PATCH 16/31] chore: fix typo

---
 .../io/weaviate/client6/v1/internal/ReuseTokenProvider.java   | 2 +-
 .../io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java     | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
index 594b0cad9..486295218 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
@@ -32,7 +32,7 @@ final class ReuseTokenProvider implements TokenProvider {
   static TokenProvider wrap(Token t, TokenProvider tp, long expiryDelta) {
     if (tp instanceof ReuseTokenProvider rtp) {
       if (t == null) {
-        // Use it directly, but set new expirty delta.
+        // Use it directly, but set new expiry delta.
         return rtp.withExpiryDelta(expiryDelta);
       }
     }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
index ca91361b5..ad12561ff 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/Flow.java
@@ -23,8 +23,8 @@ static Flow refreshToken(Token t) {
   }
 
   static Flow resourceOwnerPassword(String username, String password) {
-    final var GRANT = new ResourceOwnerPasswordCredentialsGrant(username, new Secret(password));
-    return () -> GRANT; // Reuse cached authorization grant
+    final var grant = new ResourceOwnerPasswordCredentialsGrant(username, new Secret(password));
+    return () -> grant; // Reuse cached authorization grant
   }
 
   static Flow clientCredentials(String clientId, String clientSecret) {

From 5fc3ce5ea2befa30a921025d4d57adfade1cbebb Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Fri, 15 Aug 2025 00:51:25 +0200
Subject: [PATCH 17/31] feat: add Authorization to WeaviateClientAsync

---
 .../client6/v1/api/WeaviateClientAsync.java   | 69 +++++++++++++++++--
 1 file changed, 62 insertions(+), 7 deletions(-)

diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
index 0aff9c8c4..b47d31329 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
@@ -7,10 +7,13 @@
 
 import io.weaviate.client6.v1.api.collections.WeaviateCollectionsClientAsync;
 import io.weaviate.client6.v1.internal.ObjectBuilder;
+import io.weaviate.client6.v1.internal.TokenProvider;
 import io.weaviate.client6.v1.internal.grpc.DefaultGrpcTransport;
+import io.weaviate.client6.v1.internal.grpc.GrpcChannelOptions;
 import io.weaviate.client6.v1.internal.grpc.GrpcTransport;
 import io.weaviate.client6.v1.internal.rest.DefaultRestTransport;
 import io.weaviate.client6.v1.internal.rest.RestTransport;
+import io.weaviate.client6.v1.internal.rest.RestTransportOptions;
 
 public class WeaviateClientAsync implements Closeable {
   private final RestTransport restTransport;
@@ -18,36 +21,88 @@ public class WeaviateClientAsync implements Closeable {
 
   public final WeaviateCollectionsClientAsync collections;
 
+  /**
+   * This constructor is blocking if {@link Authorization} configured,
+   * as the client will need to do the initial token exchange.
+   */
   public WeaviateClientAsync(Config config) {
-    this.restTransport = new DefaultRestTransport(config.restTransportOptions());
-    this.grpcTransport = new DefaultGrpcTransport(config.grpcTransportOptions());
+    RestTransportOptions restOpt;
+    GrpcChannelOptions grpcOpt;
+    if (config.authorization() == null) {
+      restOpt = config.restTransportOptions();
+      grpcOpt = config.grpcTransportOptions();
+    } else {
+      TokenProvider tokenProvider;
+      try (final var noAuthRest = new DefaultRestTransport(config.restTransportOptions())) {
+        tokenProvider = config.authorization().getTokenProvider(noAuthRest);
+      } catch (IOException e) {
+        // Generally IOExceptions are caught in TokenProvider internals.
+        // This one may be thrown when noAuthRest transport is auto-closed.
+        throw new WeaviateOAuthException(e);
+      }
+      restOpt = config.restTransportOptions(tokenProvider);
+      grpcOpt = config.grpcTransportOptions(tokenProvider);
+    }
+
+    this.restTransport = new DefaultRestTransport(restOpt);
+    this.grpcTransport = new DefaultGrpcTransport(grpcOpt);
 
     this.collections = new WeaviateCollectionsClientAsync(restTransport, grpcTransport);
   }
 
-  /** Connect to a local Weaviate instance. */
+  /**
+   * Connect to a local Weaviate instance.
+   *
+   * <p>
+   * This call is blocking if {@link Authorization} configured,
+   * as the client will need to do the initial token exchange.
+   */
   public static WeaviateClientAsync local() {
     return local(ObjectBuilder.identity());
   }
 
-  /** Connect to a local Weaviate instance. */
+  /**
+   * Connect to a local Weaviate instance.
+   *
+   * <p>
+   * This call is blocking if {@link Authorization} configured,
+   * as the client will need to do the initial token exchange.
+   */
   public static WeaviateClientAsync local(Function<Config.Local, ObjectBuilder<Config>> fn) {
     return new WeaviateClientAsync(fn.apply(new Config.Local()).build());
   }
 
-  /** Connect to a Weaviate Cloud instance. */
+  /**
+   * Connect to a Weaviate Cloud instance.
+   *
+   * <p>
+   * This call is blocking if {@link Authorization} configured,
+   * as the client will need to do the initial token exchange.
+   */
   public static WeaviateClientAsync wcd(String httpHost, String apiKey) {
     return wcd(httpHost, apiKey, ObjectBuilder.identity());
   }
 
-  /** Connect to a Weaviate Cloud instance. */
+  /**
+   * Connect to a Weaviate Cloud instance.
+   *
+   * <p>
+   * This call is blocking if {@link Authorization} configured,
+   * as the client will need to do the initial token exchange.
+   */
   public static WeaviateClientAsync wcd(String httpHost, String apiKey,
       Function<Config.WeaviateCloud, ObjectBuilder<Config>> fn) {
     var config = new Config.WeaviateCloud(httpHost, Authorization.apiKey(apiKey));
     return new WeaviateClientAsync(fn.apply(config).build());
   }
 
-  /** Connect to a Weaviate instance with custom configuration. */
+  /**
+   * Connect to a Weaviate instance with custom configuration.
+   *
+   * <p>
+   * This call is blocking if {@link Authorization} configured,
+   * as the client will need to do the initial token exchange.
+   */
   public static WeaviateClientAsync custom(Function<Config.Custom, ObjectBuilder<Config>> fn) {
     return new WeaviateClientAsync(Config.of(fn));
   }

From ad6ea8b5a9f804ffce05856bb084fb716f9aee52 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Fri, 15 Aug 2025 01:09:39 +0200
Subject: [PATCH 18/31] feat: implement readiness check

---
 .../io/weaviate/client6/v1/api/IsReadyRequest.java  | 13 +++++++++++++
 .../io/weaviate/client6/v1/api/WeaviateClient.java  |  5 +++++
 .../client6/v1/api/WeaviateClientAsync.java         |  5 +++++
 3 files changed, 23 insertions(+)
 create mode 100644 src/main/java/io/weaviate/client6/v1/api/IsReadyRequest.java

diff --git a/src/main/java/io/weaviate/client6/v1/api/IsReadyRequest.java b/src/main/java/io/weaviate/client6/v1/api/IsReadyRequest.java
new file mode 100644
index 000000000..bc597f8ca
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/api/IsReadyRequest.java
@@ -0,0 +1,13 @@
+package io.weaviate.client6.v1.api;
+
+import java.util.Collections;
+
+import io.weaviate.client6.v1.internal.rest.BooleanEndpoint;
+import io.weaviate.client6.v1.internal.rest.Endpoint;
+
+public record IsReadyRequest() {
+  public static final Endpoint<Void, Boolean> _ENDPOINT = BooleanEndpoint.noBody(
+      request -> "GET",
+      request -> "/.well-known/ready",
+      request -> Collections.emptyMap());
+}
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
index cf7787ae9..8c8e8ea63 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
@@ -126,6 +126,11 @@ public boolean isLive() throws IOException {
     return this.restTransport.performRequest(null, IsLiveRequest._ENDPOINT);
   }
 
+  /** Ping the server for a readiness check. */
+  public boolean isReady() throws IOException {
+    return this.restTransport.performRequest(null, IsReadyRequest._ENDPOINT);
+  }
+
   /**
    * Close {@link #restTransport} and {@link #grpcTransport}
    * and release associated resources.
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
index b47d31329..7c2320bc3 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
@@ -112,6 +112,11 @@ public CompletableFuture<Boolean> isLive() {
     return this.restTransport.performRequestAsync(null, IsLiveRequest._ENDPOINT);
   }
 
+  /** Ping the server for a readiness check. */
+  public CompletableFuture<Boolean> isReady() {
+    return this.restTransport.performRequestAsync(null, IsReadyRequest._ENDPOINT);
+  }
+
   /**
    * Close {@link #restTransport} and {@link #grpcTransport}
    * and release associated resources.

From 897225a6af3f27b9f43e8bc39537ffb8e073df75 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Fri, 15 Aug 2025 01:21:09 +0200
Subject: [PATCH 19/31] feat: add /meta endpoint

---
 .../weaviate/client6/v1/api/InstanceMetadata.java  | 12 ++++++++++++
 .../client6/v1/api/InstanceMetadataRequest.java    | 14 ++++++++++++++
 .../io/weaviate/client6/v1/api/WeaviateClient.java |  5 +++++
 .../client6/v1/api/WeaviateClientAsync.java        |  5 +++++
 4 files changed, 36 insertions(+)
 create mode 100644 src/main/java/io/weaviate/client6/v1/api/InstanceMetadata.java
 create mode 100644 src/main/java/io/weaviate/client6/v1/api/InstanceMetadataRequest.java

diff --git a/src/main/java/io/weaviate/client6/v1/api/InstanceMetadata.java b/src/main/java/io/weaviate/client6/v1/api/InstanceMetadata.java
new file mode 100644
index 000000000..9664e8490
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/api/InstanceMetadata.java
@@ -0,0 +1,12 @@
+package io.weaviate.client6.v1.api;
+
+import java.util.Map;
+
+import com.google.gson.annotations.SerializedName;
+
+public record InstanceMetadata(
+    @SerializedName("hostname") String hostName,
+    @SerializedName("version") String version,
+    @SerializedName("modules") Map<String, Object> modules,
+    @SerializedName("grpcMaxMessageSize") Long grpcMaxMessageSize) {
+}
diff --git a/src/main/java/io/weaviate/client6/v1/api/InstanceMetadataRequest.java b/src/main/java/io/weaviate/client6/v1/api/InstanceMetadataRequest.java
new file mode 100644
index 000000000..09635c9df
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/api/InstanceMetadataRequest.java
@@ -0,0 +1,14 @@
+package io.weaviate.client6.v1.api;
+
+import java.util.Collections;
+
+import io.weaviate.client6.v1.internal.rest.Endpoint;
+import io.weaviate.client6.v1.internal.rest.SimpleEndpoint;
+
+public class InstanceMetadataRequest {
+  public static final Endpoint<Void, InstanceMetadata> _ENDPOINT = SimpleEndpoint.noBody(
+      __ -> "GET",
+      __ -> "/meta",
+      __ -> Collections.emptyMap(),
+      InstanceMetadata.class);
+}
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
index 8c8e8ea63..b75045691 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
@@ -131,6 +131,11 @@ public boolean isReady() throws IOException {
     return this.restTransport.performRequest(null, IsReadyRequest._ENDPOINT);
   }
 
+  /** Get deployement metadata for the target Weaviate instance. */
+  public InstanceMetadata meta() throws IOException {
+    return this.restTransport.performRequest(null, InstanceMetadataRequest._ENDPOINT);
+  }
+
   /**
    * Close {@link #restTransport} and {@link #grpcTransport}
    * and release associated resources.
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
index 7c2320bc3..36b4c2535 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
@@ -117,6 +117,11 @@ public CompletableFuture<Boolean> isReady() {
     return this.restTransport.performRequestAsync(null, IsReadyRequest._ENDPOINT);
   }
 
+  /** Get deployement metadata for the target Weaviate instance. */
+  public CompletableFuture<InstanceMetadata> meta() throws IOException {
+    return this.restTransport.performRequestAsync(null, InstanceMetadataRequest._ENDPOINT);
+  }
+
   /**
    * Close {@link #restTransport} and {@link #grpcTransport}
    * and release associated resources.

From a1615ed533440051d34f102282b7639167da6c86 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Sun, 17 Aug 2025 21:00:12 +0200
Subject: [PATCH 20/31] feat: use non-blocking auth interceptor for async
 client

---
 .../java/io/weaviate/containers/Weaviate.java |  4 +-
 .../integration/OIDCSupportITest.java         | 44 +++++++++---
 .../weaviate/integration/PaginationITest.java |  2 +-
 .../io/weaviate/integration/SearchITest.java  |  2 +-
 .../client6/v1/api/WeaviateClient.java        |  9 ++-
 .../client6/v1/api/WeaviateClientAsync.java   |  7 +-
 .../v1/internal/AsyncTokenProvider.java       | 50 +++++++++++++
 .../client6/v1/internal/TokenProvider.java    |  2 +-
 .../rest/AuthenticationInterceptor.java       | 71 +++++++++++++++++++
 .../rest/AuthorizationInterceptor.java        | 29 --------
 .../internal/rest/DefaultRestTransport.java   | 13 ++--
 .../v1/internal/rest/RestTransport.java       |  3 +-
 .../client6/v1/api/AuthorizationTest.java     |  4 +-
 .../rest/DefaultRestTransportTest.java        |  2 +-
 14 files changed, 180 insertions(+), 62 deletions(-)
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
 delete mode 100644 src/main/java/io/weaviate/client6/v1/internal/rest/AuthorizationInterceptor.java

diff --git a/src/it/java/io/weaviate/containers/Weaviate.java b/src/it/java/io/weaviate/containers/Weaviate.java
index bd166c745..0802b097e 100644
--- a/src/it/java/io/weaviate/containers/Weaviate.java
+++ b/src/it/java/io/weaviate/containers/Weaviate.java
@@ -157,7 +157,7 @@ public void stop() {
     synchronized (this) {
       try {
         clientInstance.close(this);
-      } catch (IOException e) {
+      } catch (Exception e) {
         throw new RuntimeException(e);
       }
     }
@@ -172,7 +172,7 @@ private SharedClient(Config config, Weaviate parent) {
       this.parent = parent;
     }
 
-    private void close(Weaviate caller) throws IOException {
+    private void close(Weaviate caller) throws Exception {
       if (caller == parent) {
         super.close();
       }
diff --git a/src/it/java/io/weaviate/integration/OIDCSupportITest.java b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
index 5d9921910..0cf429ff7 100644
--- a/src/it/java/io/weaviate/integration/OIDCSupportITest.java
+++ b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
@@ -47,17 +47,17 @@ public class OIDCSupportITest extends ConcurrentTest {
       .build();
 
   @Test
-  public void test_bearerToken() throws IOException {
+  public void test_bearerToken() throws Exception {
     Assume.assumeTrue("WCS_DUMMY_CI_PW is not set", WCS_DUMMY_CI_PW != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
-    var t = TokenInterceptor.stealToken();
+    var t = SpyTokenProvider.stealToken();
     var authz = Authorization.bearerToken(t.accessToken(), t.refreshToken(), t.expiresIn());
     pingWeaviate(wcsContainer, authz);
   }
 
   @Test
-  public void test_resourceOwnerPassword() throws IOException {
+  public void test_resourceOwnerPassword() throws Exception {
     Assume.assumeTrue("WCS_DUMMY_CI_PW is not set", WCS_DUMMY_CI_PW != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
@@ -66,16 +66,15 @@ public void test_resourceOwnerPassword() throws IOException {
   }
 
   @Test
-  public void test_clientCredentials() throws IOException {
+  public void test_clientCredentials() throws Exception {
     Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
     var authz = Authorization.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
     pingWeaviate(oktaContainer, authz);
-    pingWeaviate(oktaContainer, authz);
   }
 
-  private static void pingWeaviate(final Weaviate container, Authorization authz) throws IOException {
+  private static void pingWeaviate(final Weaviate container, Authorization authz) throws Exception {
     try (final var client = container.getClient(conn -> conn.authorization(authz))) {
       Assertions.assertThat(client.isLive()).isTrue();
     }
@@ -95,11 +94,36 @@ private static boolean ping(String site) {
     }
   }
 
-  private static class TokenInterceptor implements Authorization, TokenProvider {
+  /** Test AuthenticationInterceptor works correctly in the async context. */
+  @Test
+  public void test_clientCredentials_async() throws Exception {
+    Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
+    Assume.assumeTrue("no internet connection", hasInternetConnection());
+
+    var authz = Authorization.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
+    final var client = oktaContainer.getClient(conn -> conn.authorization(authz));
+    final var async = client.async();
+
+    try {
+      Assertions.assertThat(async.isLive().get()).isTrue();
+    } catch (Exception e) {
+      Assertions.fail(e);
+    } finally {
+      client.close();
+      async.close();
+    }
+  }
+
+  /**
+   * SpyTokenProvider is an Authorization implementation that spies on the
+   * TokenProvider it creates and can expose tokens generated by it.
+   */
+  private static class SpyTokenProvider implements Authorization, TokenProvider {
+
     /** Exchange resource owner password for a token and return it. */
-    public static Token stealToken() throws IOException {
+    static Token stealToken() throws Exception {
       var authz = Authorization.resourceOwnerPassword(WCS_DUMMY_CI_USERNAME, WCS_DUMMY_CI_PW, List.of());
-      var spy = new TokenInterceptor(authz);
+      var spy = new SpyTokenProvider(authz);
       pingWeaviate(wcsContainer, spy);
       return spy.getToken();
     }
@@ -107,7 +131,7 @@ public static Token stealToken() throws IOException {
     private Authorization authorization;
     private TokenProvider tokenProvider;
 
-    private TokenInterceptor(Authorization actual) {
+    private SpyTokenProvider(Authorization actual) {
       this.authorization = actual;
     }
 
diff --git a/src/it/java/io/weaviate/integration/PaginationITest.java b/src/it/java/io/weaviate/integration/PaginationITest.java
index 3d97d0a21..5044bdb73 100644
--- a/src/it/java/io/weaviate/integration/PaginationITest.java
+++ b/src/it/java/io/weaviate/integration/PaginationITest.java
@@ -126,7 +126,7 @@ public void testWithQueryOptions() throws IOException {
   }
 
   @Test
-  public void testAsyncPaginator() throws IOException, InterruptedException, ExecutionException {
+  public void testAsyncPaginator() throws Exception, InterruptedException, ExecutionException {
     // Arrange
     var nsThings = ns("Things");
     var count = 10;
diff --git a/src/it/java/io/weaviate/integration/SearchITest.java b/src/it/java/io/weaviate/integration/SearchITest.java
index d4c132e0e..2d5d78bb9 100644
--- a/src/it/java/io/weaviate/integration/SearchITest.java
+++ b/src/it/java/io/weaviate/integration/SearchITest.java
@@ -288,7 +288,7 @@ public void testBm25() throws IOException, InterruptedException, ExecutionExcept
    * test both sync/async clients.
    */
   @Test
-  public void testBm25_async() throws IOException, InterruptedException, ExecutionException {
+  public void testBm25_async() throws Exception, InterruptedException, ExecutionException {
     var nsWords = ns("Words");
 
     try (final var async = client.async()) {
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
index b75045691..5450da135 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
@@ -1,6 +1,5 @@
 package io.weaviate.client6.v1.api;
 
-import java.io.Closeable;
 import java.io.IOException;
 import java.util.function.Function;
 
@@ -14,7 +13,7 @@
 import io.weaviate.client6.v1.internal.rest.RestTransport;
 import io.weaviate.client6.v1.internal.rest.RestTransportOptions;
 
-public class WeaviateClient implements Closeable {
+public class WeaviateClient implements AutoCloseable {
   /** Store this for {@link #async()} helper. */
   private final Config config;
 
@@ -35,8 +34,8 @@ public WeaviateClient(Config config) {
       TokenProvider tokenProvider;
       try (final var noAuthRest = new DefaultRestTransport(config.restTransportOptions())) {
         tokenProvider = config.authorization().getTokenProvider(noAuthRest);
-      } catch (IOException e) {
-        // Generally IOExceptions are caught in TokenProvider internals.
+      } catch (Exception e) {
+        // Generally exceptions are caught in TokenProvider internals.
         // This one may be thrown when noAuthRest transport is auto-closed.
         throw new WeaviateOAuthException(e);
       }
@@ -141,7 +140,7 @@ public InstanceMetadata meta() throws IOException {
    * and release associated resources.
    */
   @Override
-  public void close() throws IOException {
+  public void close() throws Exception {
     this.restTransport.close();
     this.grpcTransport.close();
   }
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
index 36b4c2535..c78915ece 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
@@ -1,6 +1,5 @@
 package io.weaviate.client6.v1.api;
 
-import java.io.Closeable;
 import java.io.IOException;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Function;
@@ -15,7 +14,7 @@
 import io.weaviate.client6.v1.internal.rest.RestTransport;
 import io.weaviate.client6.v1.internal.rest.RestTransportOptions;
 
-public class WeaviateClientAsync implements Closeable {
+public class WeaviateClientAsync implements AutoCloseable {
   private final RestTransport restTransport;
   private final GrpcTransport grpcTransport;
 
@@ -35,7 +34,7 @@ public WeaviateClientAsync(Config config) {
       TokenProvider tokenProvider;
       try (final var noAuthRest = new DefaultRestTransport(config.restTransportOptions())) {
         tokenProvider = config.authorization().getTokenProvider(noAuthRest);
-      } catch (IOException e) {
+      } catch (Exception e) {
         // Generally IOExceptions are caught in TokenProvider internals.
         // This one may be thrown when noAuthRest transport is auto-closed.
         throw new WeaviateOAuthException(e);
@@ -127,7 +126,7 @@ public CompletableFuture<InstanceMetadata> meta() throws IOException {
    * and release associated resources.
    */
   @Override
-  public void close() throws IOException {
+  public void close() throws Exception {
     this.restTransport.close();
     this.grpcTransport.close();
   }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
new file mode 100644
index 000000000..3f88da1cf
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
@@ -0,0 +1,50 @@
+package io.weaviate.client6.v1.internal;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+import io.weaviate.client6.v1.internal.TokenProvider.Token;
+
+/**
+ * AsyncTokenProvider obtains authentication tokens asynchronously
+ * and can be used in a non-blocking context.
+ *
+ * As implementors are likely to schedule token fetches on a thread pool,
+ * instances must be closed to avoid resource leaks.
+ */
+public interface AsyncTokenProvider extends AutoCloseable {
+  CompletableFuture<Token> getToken();
+
+  /**
+   * Create an {@link AsyncTokenProvider} instance from an existing
+   * {@link TokenProvider}. The inner provider MAY be called from
+   * multiple instances and MUST be thread-safe.
+   *
+   * Either use in a try-with-resources block or close after usage explicitly.
+   */
+  static AsyncTokenProvider wrap(TokenProvider tp) {
+    return new Default(tp);
+  }
+
+  /** AsyncTokenProvider fetches tokens in a single background thread. */
+  public static class Default implements AsyncTokenProvider {
+    private final ExecutorService exec;
+    private final TokenProvider provider;
+
+    Default(TokenProvider tp) {
+      this.provider = tp;
+      this.exec = Executors.newSingleThreadExecutor();
+    }
+
+    @Override
+    public CompletableFuture<Token> getToken() {
+      return CompletableFuture.supplyAsync(provider::getToken, exec);
+    }
+
+    @Override
+    public void close() throws Exception {
+      exec.shutdown();
+    }
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index 9b5a0e4fb..7e17f8c81 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -81,7 +81,7 @@ public static Token expireNever(String accessToken) {
    * Refreshing the token slightly ahead of time will help prevent
    * phony unauthorized access errors.
    *
-   * This value is currently not configuratble and should be seen
+   * This value is currently not configurable and should be seen
    * as an internal implementation detail.
    */
   static long DEFAULT_EARLY_EXPIRY = 30;
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java b/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
new file mode 100644
index 000000000..6ab6aa33c
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
@@ -0,0 +1,71 @@
+package io.weaviate.client6.v1.internal.rest;
+
+import java.io.IOException;
+
+import org.apache.hc.client5.http.async.AsyncExecCallback;
+import org.apache.hc.client5.http.async.AsyncExecChain;
+import org.apache.hc.client5.http.async.AsyncExecChain.Scope;
+import org.apache.hc.client5.http.async.AsyncExecChainHandler;
+import org.apache.hc.core5.http.EntityDetails;
+import org.apache.hc.core5.http.HttpException;
+import org.apache.hc.core5.http.HttpRequest;
+import org.apache.hc.core5.http.HttpRequestInterceptor;
+import org.apache.hc.core5.http.message.BasicHeader;
+import org.apache.hc.core5.http.nio.AsyncEntityProducer;
+import org.apache.hc.core5.http.protocol.HttpContext;
+
+import io.weaviate.client6.v1.internal.AsyncTokenProvider;
+import io.weaviate.client6.v1.internal.TokenProvider;
+import io.weaviate.client6.v1.internal.TokenProvider.Token;
+
+/**
+ * AuthenticationInterceptor can supply Authorization headers to both
+ * synchronous and asynchronous Apache HttpClient.
+ */
+class AuthenticationInterceptor implements HttpRequestInterceptor, AsyncExecChainHandler, AutoCloseable {
+  private static final String AUTHORIZATION = "Authorization";
+
+  private final TokenProvider tokenProvider;
+  private final AsyncTokenProvider tokenProviderAsync;
+
+  AuthenticationInterceptor(TokenProvider tokenProvider) {
+    this.tokenProvider = tokenProvider;
+    this.tokenProviderAsync = AsyncTokenProvider.wrap(tokenProvider);
+  }
+
+  @Override
+  public void process(HttpRequest request, EntityDetails entity, HttpContext context)
+      throws HttpException, IOException {
+    var token = tokenProvider.getToken();
+    setAuthorization(request, token);
+  }
+
+  @Override
+  public void execute(HttpRequest request, AsyncEntityProducer entityProducer, Scope scope, AsyncExecChain chain,
+      AsyncExecCallback callback) throws HttpException, IOException {
+
+    tokenProviderAsync.getToken().whenComplete((tok, error) -> {
+      if (error != null) {
+        callback.failed(error instanceof Exception ex ? ex : new RuntimeException(error));
+        return;
+      }
+
+      setAuthorization(request, tok);
+
+      try {
+        chain.proceed(request, entityProducer, scope, callback);
+      } catch (HttpException | IOException e) {
+        callback.failed(e);
+      }
+    });
+  }
+
+  private void setAuthorization(HttpRequest request, Token token) {
+    request.addHeader(new BasicHeader(AUTHORIZATION, "Bearer " + token.accessToken()));
+  }
+
+  @Override
+  public void close() throws Exception {
+    tokenProviderAsync.close();
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/AuthorizationInterceptor.java b/src/main/java/io/weaviate/client6/v1/internal/rest/AuthorizationInterceptor.java
deleted file mode 100644
index 9fe109d23..000000000
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/AuthorizationInterceptor.java
+++ /dev/null
@@ -1,29 +0,0 @@
-package io.weaviate.client6.v1.internal.rest;
-
-import java.io.IOException;
-
-import org.apache.hc.core5.http.EntityDetails;
-import org.apache.hc.core5.http.HttpException;
-import org.apache.hc.core5.http.HttpRequest;
-import org.apache.hc.core5.http.HttpRequestInterceptor;
-import org.apache.hc.core5.http.message.BasicHeader;
-import org.apache.hc.core5.http.protocol.HttpContext;
-
-import io.weaviate.client6.v1.internal.TokenProvider;
-
-class AuthorizationInterceptor implements HttpRequestInterceptor {
-  private static final String AUTHORIZATION = "Authorization";
-
-  private final TokenProvider tokenProvider;
-
-  AuthorizationInterceptor(TokenProvider tokenProvider) {
-    this.tokenProvider = tokenProvider;
-  }
-
-  @Override
-  public void process(HttpRequest request, EntityDetails entity, HttpContext context)
-      throws HttpException, IOException {
-    var token = tokenProvider.getToken().accessToken();
-    request.addHeader(new BasicHeader(AUTHORIZATION, "Bearer " + token));
-  }
-}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java b/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java
index 8e011eb23..577b79050 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java
@@ -34,6 +34,8 @@ public class DefaultRestTransport implements RestTransport {
   private final CloseableHttpAsyncClient httpClientAsync;
   private final RestTransportOptions transportOptions;
 
+  private AuthenticationInterceptor authInterceptor;
+
   public DefaultRestTransport(RestTransportOptions transportOptions) {
     this.transportOptions = transportOptions;
 
@@ -65,9 +67,9 @@ public DefaultRestTransport(RestTransportOptions transportOptions) {
     }
 
     if (transportOptions.tokenProvider() != null) {
-      var interceptor = new AuthorizationInterceptor(transportOptions.tokenProvider());
-      httpClient.addRequestInterceptorFirst(interceptor);
-      httpClientAsync.addRequestInterceptorFirst(interceptor);
+      authInterceptor = new AuthenticationInterceptor(transportOptions.tokenProvider());
+      httpClient.addRequestInterceptorFirst(authInterceptor);
+      httpClientAsync.addExecInterceptorFirst("auth", authInterceptor);
     }
 
     this.httpClient = httpClient.build();
@@ -189,8 +191,11 @@ public RestTransportOptions getTransportOptions() {
   }
 
   @Override
-  public void close() throws IOException {
+  public void close() throws Exception {
     httpClient.close();
     httpClientAsync.close(CloseMode.GRACEFUL);
+    if (authInterceptor != null) {
+      authInterceptor.close();
+    }
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/RestTransport.java b/src/main/java/io/weaviate/client6/v1/internal/rest/RestTransport.java
index 2b3d50e07..bcb50f81f 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/RestTransport.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/RestTransport.java
@@ -1,10 +1,9 @@
 package io.weaviate.client6.v1.internal.rest;
 
-import java.io.Closeable;
 import java.io.IOException;
 import java.util.concurrent.CompletableFuture;
 
-public interface RestTransport extends Closeable {
+public interface RestTransport extends AutoCloseable {
   <RequestT, ResponseT, ExceptionT> ResponseT performRequest(RequestT request,
       Endpoint<RequestT, ResponseT> endpoint)
       throws IOException;
diff --git a/src/test/java/io/weaviate/client6/v1/api/AuthorizationTest.java b/src/test/java/io/weaviate/client6/v1/api/AuthorizationTest.java
index 7e52d41a4..67a467ead 100644
--- a/src/test/java/io/weaviate/client6/v1/api/AuthorizationTest.java
+++ b/src/test/java/io/weaviate/client6/v1/api/AuthorizationTest.java
@@ -37,7 +37,7 @@ public void startMockServer() throws IOException {
   }
 
   @Test
-  public void testAuthorization_apiKey() throws IOException {
+  public void testAuthorization_apiKey() throws Exception {
     var authz = Authorization.apiKey("my-api-key");
     var transportOptions = new RestTransportOptions(
         "http", "localhost", mockServer.getLocalPort(),
@@ -60,7 +60,7 @@ public void testAuthorization_apiKey() throws IOException {
   }
 
   @After
-  public void stopMockServer() throws IOException {
+  public void stopMockServer() throws Exception {
     mockServer.stop();
     noAuthTransport.close();
   }
diff --git a/src/test/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransportTest.java b/src/test/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransportTest.java
index cf6de61a8..28909df31 100644
--- a/src/test/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransportTest.java
+++ b/src/test/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransportTest.java
@@ -73,7 +73,7 @@ public void testCustomTrustStore_async() throws IOException, ExecutionException,
   }
 
   @After
-  public void tearDown() throws IOException {
+  public void tearDown() throws Exception {
     mockServer.stop();
     transport.close();
   }

From 148cb3f52b351fd80e590f5a01a06b392c62f27c Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Sun, 17 Aug 2025 21:47:46 +0200
Subject: [PATCH 21/31] feat: use non-blocking token provider in the gRPC stub

Add another interface method to AsyncTokenProvider to
schedule the future on a custom executor.
---
 .../integration/OIDCSupportITest.java         | 56 +++++++++++--------
 .../v1/internal/AsyncTokenProvider.java       | 12 +++-
 .../internal/grpc/DefaultGrpcTransport.java   | 16 ++++--
 .../v1/internal/grpc/GrpcTransport.java       |  2 +-
 .../internal/grpc/TokenCallCredentials.java   | 37 +++++++-----
 5 files changed, 80 insertions(+), 43 deletions(-)

diff --git a/src/it/java/io/weaviate/integration/OIDCSupportITest.java b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
index 0cf429ff7..72210cc93 100644
--- a/src/it/java/io/weaviate/integration/OIDCSupportITest.java
+++ b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
@@ -4,6 +4,7 @@
 import java.net.InetSocketAddress;
 import java.net.Socket;
 import java.util.List;
+import java.util.UUID;
 
 import org.assertj.core.api.Assertions;
 import org.junit.Assume;
@@ -20,7 +21,7 @@
  * obtain a token from the OIDC provider and use it in a request to Weaviate.
  *
  * Running this test suite successfully requires talking to external services,
- * so tests will be skipped if the don't have internet. See
+ * so tests will be skipped if we don't have internet. See
  * {@link #hasInternetConnection}.
  */
 public class OIDCSupportITest extends ConcurrentTest {
@@ -28,7 +29,7 @@ public class OIDCSupportITest extends ConcurrentTest {
   private static final String WCS_DUMMY_CI_PW = System.getenv("WCS_DUMMY_CI_PW");
 
   /**
-   * Weaviate conatiner that users WCS-backed OIDC provider.
+   * Weaviate container that uses WCS-backed OIDC provider.
    * Supports ResourceOwnerPassword and RefreshToken authentication flows.
    */
   private static final Weaviate wcsContainer = Weaviate.custom()
@@ -74,6 +75,37 @@ public void test_clientCredentials() throws Exception {
     pingWeaviate(oktaContainer, authz);
   }
 
+  /**
+   * Test AuthenticationInterceptor (HTTP) / TokenCallCredentials (gRPC)
+   * work correctly in the async context.
+   */
+  @Test
+  public void test_clientCredentials_async() throws Exception {
+    Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
+    Assume.assumeTrue("no internet connection", hasInternetConnection());
+
+    var authz = Authorization.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
+    final var client = oktaContainer.getClient(conn -> conn.authorization(authz));
+    final var async = client.async();
+
+    try {
+      // Make an authenticated REST call
+      Assertions.assertThat(async.isLive().get()).isTrue();
+
+      // Make an authenticated gRPC call
+      var nsThings = ns("Things");
+      async.collections.create(nsThings);
+      var things = async.collections.use(nsThings);
+      var randomUuid = UUID.randomUUID().toString();
+      Assertions.assertThat(things.data.exists(randomUuid).get()).isFalse();
+    } catch (Exception e) {
+      Assertions.fail(e);
+    } finally {
+      client.close();
+      async.close();
+    }
+  }
+
   private static void pingWeaviate(final Weaviate container, Authorization authz) throws Exception {
     try (final var client = container.getClient(conn -> conn.authorization(authz))) {
       Assertions.assertThat(client.isLive()).isTrue();
@@ -94,26 +126,6 @@ private static boolean ping(String site) {
     }
   }
 
-  /** Test AuthenticationInterceptor works correctly in the async context. */
-  @Test
-  public void test_clientCredentials_async() throws Exception {
-    Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
-    Assume.assumeTrue("no internet connection", hasInternetConnection());
-
-    var authz = Authorization.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
-    final var client = oktaContainer.getClient(conn -> conn.authorization(authz));
-    final var async = client.async();
-
-    try {
-      Assertions.assertThat(async.isLive().get()).isTrue();
-    } catch (Exception e) {
-      Assertions.fail(e);
-    } finally {
-      client.close();
-      async.close();
-    }
-  }
-
   /**
    * SpyTokenProvider is an Authorization implementation that spies on the
    * TokenProvider it creates and can expose tokens generated by it.
diff --git a/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
index 3f88da1cf..007737209 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
@@ -1,6 +1,7 @@
 package io.weaviate.client6.v1.internal;
 
 import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executor;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
 
@@ -16,6 +17,8 @@
 public interface AsyncTokenProvider extends AutoCloseable {
   CompletableFuture<Token> getToken();
 
+  CompletableFuture<Token> getToken(Executor executor);
+
   /**
    * Create an {@link AsyncTokenProvider} instance from an existing
    * {@link TokenProvider}. The inner provider MAY be called from
@@ -37,9 +40,16 @@ public static class Default implements AsyncTokenProvider {
       this.exec = Executors.newSingleThreadExecutor();
     }
 
+    /** Get token with the default single-thread executor. */
     @Override
     public CompletableFuture<Token> getToken() {
-      return CompletableFuture.supplyAsync(provider::getToken, exec);
+      return getToken(exec);
+    }
+
+    /** Get token with a custom executor. */
+    @Override
+    public CompletableFuture<Token> getToken(Executor executor) {
+      return CompletableFuture.supplyAsync(provider::getToken, executor);
     }
 
     @Override
diff --git a/src/main/java/io/weaviate/client6/v1/internal/grpc/DefaultGrpcTransport.java b/src/main/java/io/weaviate/client6/v1/internal/grpc/DefaultGrpcTransport.java
index 7655db36a..c905fbc0f 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/grpc/DefaultGrpcTransport.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/grpc/DefaultGrpcTransport.java
@@ -1,6 +1,5 @@
 package io.weaviate.client6.v1.internal.grpc;
 
-import java.io.IOException;
 import java.util.concurrent.CompletableFuture;
 
 import javax.net.ssl.SSLException;
@@ -26,6 +25,8 @@ public final class DefaultGrpcTransport implements GrpcTransport {
   private final WeaviateBlockingStub blockingStub;
   private final WeaviateFutureStub futureStub;
 
+  private TokenCallCredentials callCredentials;
+
   public DefaultGrpcTransport(GrpcChannelOptions transportOptions) {
     this.channel = buildChannel(transportOptions);
 
@@ -36,9 +37,9 @@ public DefaultGrpcTransport(GrpcChannelOptions transportOptions) {
         .withInterceptors(MetadataUtils.newAttachHeadersInterceptor(transportOptions.headers()));
 
     if (transportOptions.tokenProvider() != null) {
-      var credentials = new TokenCallCredentials(transportOptions.tokenProvider());
-      blockingStub = blockingStub.withCallCredentials(credentials);
-      futureStub = futureStub.withCallCredentials(credentials);
+      callCredentials = new TokenCallCredentials(transportOptions.tokenProvider());
+      blockingStub = blockingStub.withCallCredentials(callCredentials);
+      futureStub = futureStub.withCallCredentials(callCredentials);
     }
 
     this.blockingStub = blockingStub;
@@ -121,7 +122,10 @@ private static ManagedChannel buildChannel(GrpcChannelOptions transportOptions)
   }
 
   @Override
-  public void close() throws IOException {
-    this.channel.shutdown();
+  public void close() throws Exception {
+    channel.shutdown();
+    if (callCredentials != null) {
+      callCredentials.close();
+    }
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/grpc/GrpcTransport.java b/src/main/java/io/weaviate/client6/v1/internal/grpc/GrpcTransport.java
index a0fddbc67..952bfc336 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/grpc/GrpcTransport.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/grpc/GrpcTransport.java
@@ -3,7 +3,7 @@
 import java.io.Closeable;
 import java.util.concurrent.CompletableFuture;
 
-public interface GrpcTransport extends Closeable {
+public interface GrpcTransport extends AutoCloseable {
   <RequestT, RequestM, ReplyM, ResponseT> ResponseT performRequest(RequestT request,
       Rpc<RequestT, RequestM, ResponseT, ReplyM> rpc);
 
diff --git a/src/main/java/io/weaviate/client6/v1/internal/grpc/TokenCallCredentials.java b/src/main/java/io/weaviate/client6/v1/internal/grpc/TokenCallCredentials.java
index c24a9093a..c69696682 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/grpc/TokenCallCredentials.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/grpc/TokenCallCredentials.java
@@ -5,29 +5,40 @@
 import io.grpc.CallCredentials;
 import io.grpc.Metadata;
 import io.grpc.Status;
+import io.weaviate.client6.v1.internal.AsyncTokenProvider;
 import io.weaviate.client6.v1.internal.TokenProvider;
 
-class TokenCallCredentials extends CallCredentials {
+class TokenCallCredentials extends CallCredentials implements AutoCloseable {
   private static final Metadata.Key<String> AUTHORIZATION = Metadata.Key.of("Authorization",
       Metadata.ASCII_STRING_MARSHALLER);
 
-  private final TokenProvider tokenProvider;
+  /**
+   * Since {@link #applyRequestMetadata} accepts an {@link Executor} anyways,
+   * we can always just use an async provider, instead of creating 2 separate
+   * instances for it.
+   */
+  private final AsyncTokenProvider tokenProviderAsync;
 
   TokenCallCredentials(TokenProvider tokenProvider) {
-    this.tokenProvider = tokenProvider;
+    this.tokenProviderAsync = AsyncTokenProvider.wrap(tokenProvider);
   }
 
   @Override
   public void applyRequestMetadata(RequestInfo requestInfo, Executor executor, MetadataApplier metadataApplier) {
-    executor.execute(() -> {
-      try {
-        var headers = new Metadata();
-        var token = tokenProvider.getToken().accessToken();
-        headers.put(AUTHORIZATION, "Bearer " + token);
-        metadataApplier.apply(headers);
-      } catch (Exception e) {
-        metadataApplier.fail(Status.UNAUTHENTICATED.withCause(e));
-      }
-    });
+    tokenProviderAsync.getToken(executor)
+        .whenComplete((tok, ex) -> {
+          if (ex != null) {
+            metadataApplier.fail(Status.UNAUTHENTICATED.withCause(ex));
+            return;
+          }
+          var headers = new Metadata();
+          headers.put(AUTHORIZATION, "Bearer " + tok.accessToken());
+          metadataApplier.apply(headers);
+        });
+  }
+
+  @Override
+  public void close() throws Exception {
+    tokenProviderAsync.close();
   }
 }

From b519b195055cb2d50afc4b8200fca4945c73dbfd Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Sun, 17 Aug 2025 21:57:04 +0200
Subject: [PATCH 22/31] test: target latest Weavite version (1.32.3)

---
 src/it/java/io/weaviate/containers/Weaviate.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/it/java/io/weaviate/containers/Weaviate.java b/src/it/java/io/weaviate/containers/Weaviate.java
index 0802b097e..1a7da8e57 100644
--- a/src/it/java/io/weaviate/containers/Weaviate.java
+++ b/src/it/java/io/weaviate/containers/Weaviate.java
@@ -15,7 +15,7 @@
 import io.weaviate.client6.v1.internal.ObjectBuilder;
 
 public class Weaviate extends WeaviateContainer {
-  public static final String VERSION = "1.29.1";
+  public static final String VERSION = "1.32.3";
   public static final String DOCKER_IMAGE = "semitechnologies/weaviate";
 
   private volatile SharedClient clientInstance;

From 887a64bedba7339b109b38e8b8bd05fa06bcf761 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Sun, 17 Aug 2025 22:25:48 +0200
Subject: [PATCH 23/31] refactor: use shared ExecutorService in
 AsyncTokenProvider.Default

---
 .../v1/internal/AsyncTokenProvider.java       | 29 ++++++++++++++++---
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
index 007737209..e30d389e0 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
@@ -30,14 +30,29 @@ static AsyncTokenProvider wrap(TokenProvider tp) {
     return new Default(tp);
   }
 
-  /** AsyncTokenProvider fetches tokens in a single background thread. */
+  /**
+   * AsyncTokenProvider fetches tokens in a
+   * <i>shared single background thread</i>.
+   */
   public static class Default implements AsyncTokenProvider {
-    private final ExecutorService exec;
+    /**
+     * Shared executor service. This way all instances
+     * can share the same thread pool.
+     */
+    private static ExecutorService exec;
+    /** Shut down {@link #exec} once refCount reaches 0. */
+    private static int refCount = 0;
+
     private final TokenProvider provider;
 
     Default(TokenProvider tp) {
+      synchronized (Default.class) {
+        if (refCount == 0) {
+          exec = Executors.newSingleThreadExecutor();
+        }
+        refCount++;
+      }
       this.provider = tp;
-      this.exec = Executors.newSingleThreadExecutor();
     }
 
     /** Get token with the default single-thread executor. */
@@ -54,7 +69,13 @@ public CompletableFuture<Token> getToken(Executor executor) {
 
     @Override
     public void close() throws Exception {
-      exec.shutdown();
+      synchronized (Default.class) {
+        refCount--;
+        if (refCount == 0 && exec != null) {
+          exec.shutdown();
+          exec = null;
+        }
+      }
     }
   }
 }

From 75f8bf68f4929da9f8ab4f1fde1d1ebde2114893 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Sun, 17 Aug 2025 22:32:12 +0200
Subject: [PATCH 24/31] chore: add javadoc

---
 .../v1/internal/rest/AuthenticationInterceptor.java       | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java b/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
index 6ab6aa33c..a66752379 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
@@ -33,6 +33,10 @@ class AuthenticationInterceptor implements HttpRequestInterceptor, AsyncExecChai
     this.tokenProviderAsync = AsyncTokenProvider.wrap(tokenProvider);
   }
 
+  /**
+   * Add Authorization header to a blocking request.
+   * See {@link HttpRequestInterceptor}.
+   */
   @Override
   public void process(HttpRequest request, EntityDetails entity, HttpContext context)
       throws HttpException, IOException {
@@ -40,6 +44,10 @@ public void process(HttpRequest request, EntityDetails entity, HttpContext conte
     setAuthorization(request, token);
   }
 
+  /**
+   * Add Authorization header to a non-blocking request.
+   * See {@link AsyncExecChainHandler}.
+   */
   @Override
   public void execute(HttpRequest request, AsyncEntityProducer entityProducer, Scope scope, AsyncExecChain chain,
       AsyncExecCallback callback) throws HttpException, IOException {

From a898ff9c8fde500f1696bbe2670075079eb1ec10 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Mon, 18 Aug 2025 10:13:17 +0200
Subject: [PATCH 25/31] chore(README): add example of using shaded dependency

---
 README.md | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 5556e234e..36a740b9e 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,6 @@ Official Weaviate Java Client.
 To start using Weaviate Java Client add the dependency to `pom.xml`:
 
 ```xml
-
 <dependency>
     <groupId>io.weaviate</groupId>
     <artifactId>client6</artifactId>
@@ -19,9 +18,17 @@ To start using Weaviate Java Client add the dependency to `pom.xml`:
 
 ### Uber JAR🫙
 
-If you're building a uber-JAR with something like `maven-assembly-plugin`, use a shaded version with classifier `all`.  
+If you're building a uber-JAR with something like `maven-assembly-plugin`, use a shaded version with classifier `all`.
 This ensures that all dynamically-loaded dependecies of `io.grpc` are resolved correctly.
 
+```xml
+<dependency>
+    <groupId>io.weaviate</groupId>
+    <artifactId>client6</artifactId>
+    <version>6.0.0-beta4</version>
+    <classifier>all</classifier>
+</dependency>
+```
 
 ### Gson and reflective access to internal JDK classes
 

From 3d0df1be78f541b68a5310fbc1442e48d561ebc6 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Mon, 18 Aug 2025 19:11:41 +0200
Subject: [PATCH 26/31] fix: refresh tokens in the background

It is possible for a refresh_token to expire after a long
period of inactivity depending on the IdP.
This ensures that a new token is fetched at least once after
the access_token expires.
---
 .../v1/internal/AsyncTokenProvider.java       |  2 +
 .../v1/internal/BackgroundTokenProvider.java  | 62 +++++++++++++++++++
 .../v1/internal/ExchangeTokenProvider.java    |  5 ++
 .../v1/internal/ReuseTokenProvider.java       |  7 +++
 .../client6/v1/internal/TokenProvider.java    | 36 +++++++++--
 .../internal/grpc/DefaultGrpcTransport.java   |  2 +-
 .../oidc/nimbus/RefreshTokenFlow.java         |  4 ++
 .../rest/AuthenticationInterceptor.java       |  1 +
 .../internal/rest/DefaultRestTransport.java   |  2 +-
 9 files changed, 113 insertions(+), 8 deletions(-)
 create mode 100644 src/main/java/io/weaviate/client6/v1/internal/BackgroundTokenProvider.java

diff --git a/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
index e30d389e0..ec083d274 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/AsyncTokenProvider.java
@@ -69,6 +69,8 @@ public CompletableFuture<Token> getToken(Executor executor) {
 
     @Override
     public void close() throws Exception {
+      provider.close();
+
       synchronized (Default.class) {
         refCount--;
         if (refCount == 0 && exec != null) {
diff --git a/src/main/java/io/weaviate/client6/v1/internal/BackgroundTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/BackgroundTokenProvider.java
new file mode 100644
index 000000000..4123952f7
--- /dev/null
+++ b/src/main/java/io/weaviate/client6/v1/internal/BackgroundTokenProvider.java
@@ -0,0 +1,62 @@
+package io.weaviate.client6.v1.internal;
+
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+public class BackgroundTokenProvider implements TokenProvider {
+  private final ScheduledExecutorService exec;
+  private final TokenProvider provider;
+
+  /**
+   * Create a background task to periodically refresh the token.
+   *
+   * <p>
+   * This method will wrap the TokenProvider in {@link ReuseTokenProvider}
+   * before passing it on to the constructor to cache the token
+   * in-between the refreshes.
+   *
+   * If TokenProvider is an instance of BackgroundTokenProvider
+   * it is returned immediately.
+   */
+  public static TokenProvider wrap(TokenProvider tp) {
+    if (tp instanceof BackgroundTokenProvider) {
+      return tp;
+    }
+    return new BackgroundTokenProvider(ReuseTokenProvider.wrap(null, tp));
+  }
+
+  private BackgroundTokenProvider(TokenProvider tp) {
+    this.provider = tp;
+    this.exec = Executors.newSingleThreadScheduledExecutor();
+
+    scheduleNextRefresh();
+  }
+
+  @Override
+  public Token getToken() {
+    return provider.getToken();
+  }
+
+  /**
+   * Fetch the token and schedule a task to refresh it
+   * after {@link Token#expiresIn} seconds. The next
+   * refresh task is scheduled immediately afterwards.
+   *
+   * If {@link Token#neverExpires} this method returns
+   * early and the next refresh task is never scheduled.
+   */
+  private void scheduleNextRefresh() {
+    var t = getToken();
+    if (t.neverExpires()) {
+      return;
+    }
+    exec.schedule(this::scheduleNextRefresh, t.expiresIn(), TimeUnit.SECONDS);
+  }
+
+  @Override
+  public void close() throws Exception {
+    System.out.println("BackgroundTokenProvider::close");
+    exec.shutdown();
+  }
+}
diff --git a/src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java
index 175dd13a9..40bf7b66d 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ExchangeTokenProvider.java
@@ -29,4 +29,9 @@ class ExchangeTokenProvider implements TokenProvider {
   public Token getToken() {
     return bearer.getToken();
   }
+
+  @Override
+  public void close() throws Exception {
+    bearer.close();
+  }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
index 486295218..8f71580d6 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/ReuseTokenProvider.java
@@ -28,6 +28,8 @@ final class ReuseTokenProvider implements TokenProvider {
    * Create new {@link ReuseTokenProvider} from another {@link TokenProvider}.
    * Wrapping an instance ReuseTokenProvider returns that instance if the token is
    * {@code null}, so this method is safe to call with any TokenProvider.
+   *
+   * @return A TokenProvider.
    */
   static TokenProvider wrap(Token t, TokenProvider tp, long expiryDelta) {
     if (tp instanceof ReuseTokenProvider rtp) {
@@ -82,4 +84,9 @@ public Token getToken() {
     }
     return token;
   }
+
+  @Override
+  public void close() throws Exception {
+    provider.close();
+  }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index 7e17f8c81..397ad9a3a 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -9,7 +9,7 @@
 
 /** TokenProvider obtains authentication tokens. */
 @FunctionalInterface
-public interface TokenProvider {
+public interface TokenProvider extends AutoCloseable {
   Token getToken();
 
   /** Token represents an access_token + refresh_token pair. */
@@ -19,12 +19,17 @@ public record Token(String accessToken, String refreshToken, Instant createdAt,
      * Tokens created with {@link #expireNever} are always valid.
      */
     public boolean isValid() {
-      if (expiresIn == -1) {
+      if (neverExpires()) {
         return true;
       }
       return Instant.now().isBefore(createdAt.plusSeconds(expiresIn - expiryDelta));
     }
 
+    /** Returns {@code true} if this token is always valid. */
+    public boolean neverExpires() {
+      return expiresIn == -1;
+    }
+
     /**
      * Set early expiry for the Token.
      *
@@ -39,6 +44,11 @@ public Token withExpiryDelta(long expiryDelta) {
       return new Token(accessToken, refreshToken, createdAt, expiresIn, expiryDelta);
     }
 
+    /** Create a token with a different refresh_token. */
+    public Token withRefreshToken(String refreshToken) {
+      return new Token(accessToken, refreshToken, createdAt, expiresIn, expiryDelta);
+    }
+
     /**
      * Create a token with an expiration and a refresh_token.
      *
@@ -112,7 +122,7 @@ public static TokenProvider staticToken(String accessToken) {
   public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, String refreshToken, long expiresIn) {
     final var token = Token.expireAfter(accessToken, refreshToken, expiresIn);
     final var provider = NimbusTokenProvider.refreshToken(oidc, token);
-    return reuse(token, provider, DEFAULT_EARLY_EXPIRY);
+    return background(reuse(token, provider, DEFAULT_EARLY_EXPIRY));
   }
 
   /**
@@ -123,12 +133,12 @@ public static TokenProvider bearerToken(OidcConfig oidc, String accessToken, Str
    * @param password Resource owner password.
    *
    * @return Internal TokenProvider implementation.
-   * @throws WeaviateOAuthException if an error occured at any point of the token
+   * @throws WeaviateOAuthException if an error occurred at any point of the token
    *                                exchange process.
    */
   public static TokenProvider resourceOwnerPassword(OidcConfig oidc, String username, String password) {
     final var passwordGrant = NimbusTokenProvider.resourceOwnerPassword(oidc, username, password);
-    return reuse(null, exchange(oidc, passwordGrant), DEFAULT_EARLY_EXPIRY);
+    return background(reuse(null, exchange(oidc, passwordGrant), DEFAULT_EARLY_EXPIRY));
   }
 
   /**
@@ -139,7 +149,7 @@ public static TokenProvider resourceOwnerPassword(OidcConfig oidc, String userna
    * @param clientSecret Client secret.
    *
    * @return Internal TokenProvider implementation.
-   * @throws WeaviateOAuthException if an error occured at any point while
+   * @throws WeaviateOAuthException if an error occurred at any point while
    *                                obtaining a new token.
    */
   public static TokenProvider clientCredentials(OidcConfig oidc, String clientId, String clientSecret) {
@@ -170,6 +180,14 @@ static TokenProvider reuse(Token t, TokenProvider tp, long expiryDelta) {
     return ReuseTokenProvider.wrap(t, tp, expiryDelta);
   }
 
+  /**
+   * Obtain a TokenProvider which refreshes tokens in a background thread.
+   * This ensures a refresh_token doesn't become stale.
+   */
+  static TokenProvider background(TokenProvider tp) {
+    return BackgroundTokenProvider.wrap(tp);
+  }
+
   public record ProviderMetadata(URI tokenEndpoint) {
   }
 
@@ -186,4 +204,10 @@ public static boolean isMicrosoft(OidcConfig oidc) {
     return metadata.tokenEndpoint().getHost().contains("login.microsoftonline.com");
   }
 
+  /**
+   * Implementations which need to dispose of created resources,
+   * e.g. thread pools, should override this method.
+   */
+  default void close() throws Exception {
+  }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/grpc/DefaultGrpcTransport.java b/src/main/java/io/weaviate/client6/v1/internal/grpc/DefaultGrpcTransport.java
index c905fbc0f..a9a50c200 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/grpc/DefaultGrpcTransport.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/grpc/DefaultGrpcTransport.java
@@ -37,7 +37,7 @@ public DefaultGrpcTransport(GrpcChannelOptions transportOptions) {
         .withInterceptors(MetadataUtils.newAttachHeadersInterceptor(transportOptions.headers()));
 
     if (transportOptions.tokenProvider() != null) {
-      callCredentials = new TokenCallCredentials(transportOptions.tokenProvider());
+      this.callCredentials = new TokenCallCredentials(transportOptions.tokenProvider());
       blockingStub = blockingStub.withCallCredentials(callCredentials);
       futureStub = futureStub.withCallCredentials(callCredentials);
     }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/RefreshTokenFlow.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/RefreshTokenFlow.java
index afb1ee1bf..ce7e18df3 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/RefreshTokenFlow.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/RefreshTokenFlow.java
@@ -27,6 +27,10 @@ public AuthorizationGrant getAuthorizationGrant() {
     return new RefreshTokenGrant(new RefreshToken(t.refreshToken()));
   }
 
+  public String getRefreshToken() {
+    return t.refreshToken();
+  }
+
   public void setToken(Token t) {
     this.t = t;
   }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java b/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
index a66752379..129c8c5de 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
@@ -74,6 +74,7 @@ private void setAuthorization(HttpRequest request, Token token) {
 
   @Override
   public void close() throws Exception {
+    tokenProvider.close();
     tokenProviderAsync.close();
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java b/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java
index 577b79050..bf7896b03 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/DefaultRestTransport.java
@@ -67,7 +67,7 @@ public DefaultRestTransport(RestTransportOptions transportOptions) {
     }
 
     if (transportOptions.tokenProvider() != null) {
-      authInterceptor = new AuthenticationInterceptor(transportOptions.tokenProvider());
+      this.authInterceptor = new AuthenticationInterceptor(transportOptions.tokenProvider());
       httpClient.addRequestInterceptorFirst(authInterceptor);
       httpClientAsync.addExecInterceptorFirst("auth", authInterceptor);
     }

From ba62298399bebe190c7245953de83a55ba140df8 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Mon, 18 Aug 2025 19:12:12 +0200
Subject: [PATCH 27/31] fix: reuse old refresh_token if the new one was not
 returned

---
 .../v1/internal/oidc/nimbus/NimbusTokenProvider.java        | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
index 148264aa1..5ae7bc3ac 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/NimbusTokenProvider.java
@@ -100,6 +100,12 @@ public Token getToken() {
         : Token.expireAfter(accessToken.getValue(), refreshToken.getValue(), accessToken.getLifetime());
 
     if (flow instanceof RefreshTokenFlow rtf) {
+      // Some IdP servers may omit refresh_token from the response if it is
+      // sufficiently long-lived. In such case we continue reusing the old one.
+      if (newToken.refreshToken() == null) {
+        var rt = rtf.getRefreshToken();
+        newToken = newToken.withRefreshToken(rt);
+      }
       rtf.setToken(newToken);
     }
 

From 909f1e9dddb517dd18807ea839e1d60d7dc1cb85 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Mon, 18 Aug 2025 19:22:54 +0200
Subject: [PATCH 28/31] chore: rename Authorization -> Authentication

---
 .../integration/OIDCSupportITest.java         | 40 +++++++++----------
 ...Authorization.java => Authentication.java} | 28 ++++++-------
 .../io/weaviate/client6/v1/api/Config.java    | 24 +++++------
 .../client6/v1/api/WeaviateClient.java        |  6 +--
 .../client6/v1/api/WeaviateClientAsync.java   | 18 ++++-----
 ...ationTest.java => AuthenticationTest.java} |  6 +--
 6 files changed, 61 insertions(+), 61 deletions(-)
 rename src/main/java/io/weaviate/client6/v1/api/{Authorization.java => Authentication.java} (67%)
 rename src/test/java/io/weaviate/client6/v1/api/{AuthorizationTest.java => AuthenticationTest.java} (93%)

diff --git a/src/it/java/io/weaviate/integration/OIDCSupportITest.java b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
index 72210cc93..3a115649d 100644
--- a/src/it/java/io/weaviate/integration/OIDCSupportITest.java
+++ b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
@@ -11,13 +11,13 @@
 import org.junit.Test;
 
 import io.weaviate.ConcurrentTest;
-import io.weaviate.client6.v1.api.Authorization;
+import io.weaviate.client6.v1.api.Authentication;
 import io.weaviate.client6.v1.internal.TokenProvider;
 import io.weaviate.client6.v1.internal.rest.RestTransport;
 import io.weaviate.containers.Weaviate;
 
 /**
- * Test that the client can use one of the supported authorization flows to
+ * Test that the client can use one of the supported authentication flows to
  * obtain a token from the OIDC provider and use it in a request to Weaviate.
  *
  * Running this test suite successfully requires talking to external services,
@@ -53,8 +53,8 @@ public void test_bearerToken() throws Exception {
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
     var t = SpyTokenProvider.stealToken();
-    var authz = Authorization.bearerToken(t.accessToken(), t.refreshToken(), t.expiresIn());
-    pingWeaviate(wcsContainer, authz);
+    var auth = Authentication.bearerToken(t.accessToken(), t.refreshToken(), t.expiresIn());
+    pingWeaviate(wcsContainer, auth);
   }
 
   @Test
@@ -62,8 +62,8 @@ public void test_resourceOwnerPassword() throws Exception {
     Assume.assumeTrue("WCS_DUMMY_CI_PW is not set", WCS_DUMMY_CI_PW != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
-    var authz = Authorization.resourceOwnerPassword(WCS_DUMMY_CI_USERNAME, WCS_DUMMY_CI_PW, List.of());
-    pingWeaviate(wcsContainer, authz);
+    var auth = Authentication.resourceOwnerPassword(WCS_DUMMY_CI_USERNAME, WCS_DUMMY_CI_PW, List.of());
+    pingWeaviate(wcsContainer, auth);
   }
 
   @Test
@@ -71,8 +71,8 @@ public void test_clientCredentials() throws Exception {
     Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
-    var authz = Authorization.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
-    pingWeaviate(oktaContainer, authz);
+    var auth = Authentication.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
+    pingWeaviate(oktaContainer, auth);
   }
 
   /**
@@ -84,8 +84,8 @@ public void test_clientCredentials_async() throws Exception {
     Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
-    var authz = Authorization.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
-    final var client = oktaContainer.getClient(conn -> conn.authorization(authz));
+    var auth = Authentication.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
+    final var client = oktaContainer.getClient(conn -> conn.authentication(auth));
     final var async = client.async();
 
     try {
@@ -106,8 +106,8 @@ public void test_clientCredentials_async() throws Exception {
     }
   }
 
-  private static void pingWeaviate(final Weaviate container, Authorization authz) throws Exception {
-    try (final var client = container.getClient(conn -> conn.authorization(authz))) {
+  private static void pingWeaviate(final Weaviate container, Authentication auth) throws Exception {
+    try (final var client = container.getClient(conn -> conn.authentication(auth))) {
       Assertions.assertThat(client.isLive()).isTrue();
     }
   }
@@ -127,29 +127,29 @@ private static boolean ping(String site) {
   }
 
   /**
-   * SpyTokenProvider is an Authorization implementation that spies on the
+   * SpyTokenProvider is an Authentication implementation that spies on the
    * TokenProvider it creates and can expose tokens generated by it.
    */
-  private static class SpyTokenProvider implements Authorization, TokenProvider {
+  private static class SpyTokenProvider implements Authentication, TokenProvider {
 
     /** Exchange resource owner password for a token and return it. */
     static Token stealToken() throws Exception {
-      var authz = Authorization.resourceOwnerPassword(WCS_DUMMY_CI_USERNAME, WCS_DUMMY_CI_PW, List.of());
-      var spy = new SpyTokenProvider(authz);
+      var auth = Authentication.resourceOwnerPassword(WCS_DUMMY_CI_USERNAME, WCS_DUMMY_CI_PW, List.of());
+      var spy = new SpyTokenProvider(auth);
       pingWeaviate(wcsContainer, spy);
       return spy.getToken();
     }
 
-    private Authorization authorization;
+    private Authentication authentication;
     private TokenProvider tokenProvider;
 
-    private SpyTokenProvider(Authorization actual) {
-      this.authorization = actual;
+    private SpyTokenProvider(Authentication actual) {
+      this.authentication = actual;
     }
 
     @Override
     public TokenProvider getTokenProvider(RestTransport transport) {
-      tokenProvider = authorization.getTokenProvider(transport);
+      tokenProvider = authentication.getTokenProvider(transport);
       return this;
     }
 
diff --git a/src/main/java/io/weaviate/client6/v1/api/Authorization.java b/src/main/java/io/weaviate/client6/v1/api/Authentication.java
similarity index 67%
rename from src/main/java/io/weaviate/client6/v1/api/Authorization.java
rename to src/main/java/io/weaviate/client6/v1/api/Authentication.java
index 329d655d0..22a7d4a34 100644
--- a/src/main/java/io/weaviate/client6/v1/api/Authorization.java
+++ b/src/main/java/io/weaviate/client6/v1/api/Authentication.java
@@ -7,31 +7,31 @@
 import io.weaviate.client6.v1.internal.oidc.OidcUtils;
 import io.weaviate.client6.v1.internal.rest.RestTransport;
 
-public interface Authorization {
+public interface Authentication {
   TokenProvider getTokenProvider(RestTransport transport);
 
   /**
-   * Authorize using a static API key.
+   * Authenticate using a static API key.
    *
    * @param apiKey Weaviate API key.
    */
-  public static Authorization apiKey(String apiKey) {
+  public static Authentication apiKey(String apiKey) {
     return __ -> TokenProvider.staticToken(apiKey);
   }
 
   /**
-   * Authorize using an existing access_token + refresh_token
+   * Authenticate using an existing access_token + refresh_token
    * pair.
    *
    * @param accessToken  Access token.
    * @param refreshToken Refresh token.
    * @param expiresIn    Remaining token lifetime in seconds.
    *
-   * @return Authorization provider.
+   * @return Authentication provider.
    * @throws WeaviateOAuthException if an error occurred at any point of the
    *                                exchange process.
    */
-  public static Authorization bearerToken(String accessToken, String refreshToken, long expiresIn) {
+  public static Authentication bearerToken(String accessToken, String refreshToken, long expiresIn) {
     return transport -> {
       OidcConfig oidc = OidcUtils.getConfig(transport);
       return TokenProvider.bearerToken(oidc, accessToken, refreshToken, expiresIn);
@@ -39,17 +39,17 @@ public static Authorization bearerToken(String accessToken, String refreshToken,
   }
 
   /**
-   * Authorize using Resource Owner Password authorization grant.
+   * Authenticate using Resource Owner Password authorization grant.
    *
    * @param username Resource owner username.
    * @param password Resource owner password.
    * @param scopes   Client scopes.
    *
-   * @return Authorization provider.
-   * @throws WeaviateOAuthException if an error occured at any point of the token
+   * @return Authentication provider.
+   * @throws WeaviateOAuthException if an error occurred at any point of the token
    *                                exchange process.
    */
-  public static Authorization resourceOwnerPassword(String username, String password, List<String> scopes) {
+  public static Authentication resourceOwnerPassword(String username, String password, List<String> scopes) {
     return transport -> {
       OidcConfig oidc = OidcUtils.getConfig(transport).withScopes(scopes).withScopes("offline_access");
       return TokenProvider.resourceOwnerPassword(oidc, username, password);
@@ -57,17 +57,17 @@ public static Authorization resourceOwnerPassword(String username, String passwo
   }
 
   /**
-   * Authorize using Client Credentials authorization grant.
+   * Authenticate using Client Credentials authorization grant.
    *
    * @param clientId     Client ID.
    * @param clientSecret Client secret.
    * @param scopes       Client scopes.
    *
-   * @return Authorization provider.
-   * @throws WeaviateOAuthException if an error occured at any point while
+   * @return Authentication provider.
+   * @throws WeaviateOAuthException if an error occurred at any point while
    *                                obtaining a new token.
    */
-  public static Authorization clientCredentials(String clientId, String clientSecret, List<String> scopes) {
+  public static Authentication clientCredentials(String clientId, String clientSecret, List<String> scopes) {
     return transport -> {
       OidcConfig oidc = OidcUtils.getConfig(transport).withScopes(scopes);
       if (oidc.scopes().isEmpty() && TokenProvider.isMicrosoft(oidc)) {
diff --git a/src/main/java/io/weaviate/client6/v1/api/Config.java b/src/main/java/io/weaviate/client6/v1/api/Config.java
index 3cbe4684f..a14f01290 100644
--- a/src/main/java/io/weaviate/client6/v1/api/Config.java
+++ b/src/main/java/io/weaviate/client6/v1/api/Config.java
@@ -19,7 +19,7 @@ public record Config(
     String grpcHost,
     int grpcPort,
     Map<String, String> headers,
-    Authorization authorization,
+    Authentication authentication,
     TrustManagerFactory trustManagerFactory) {
 
   public static Config of(Function<Custom, ObjectBuilder<Config>> fn) {
@@ -34,7 +34,7 @@ private Config(Builder<?> builder) {
         builder.grpcHost,
         builder.grpcPort,
         builder.headers,
-        builder.authorization,
+        builder.authentication,
         builder.trustManagerFactory);
   }
 
@@ -61,7 +61,7 @@ private abstract static class Builder<SELF extends Builder<SELF>> implements Obj
     protected int httpPort;
     protected String grpcHost;
     protected int grpcPort;
-    protected Authorization authorization;
+    protected Authentication authentication;
     protected TrustManagerFactory trustManagerFactory;
     protected Map<String, String> headers = new HashMap<>();
 
@@ -111,12 +111,12 @@ protected SELF trustManagerFactory(TrustManagerFactory tmf) {
     }
 
     /**
-     * Set authorization method. Setting this to {@code null} or omitting
-     * will not use any authorization mechanism.
+     * Set authentication method. Setting this to {@code null} or omitting
+     * will not use any authentication mechanism.
      */
     @SuppressWarnings("unchecked")
-    public SELF authorization(Authorization authz) {
-      this.authorization = authz;
+    public SELF authentication(Authentication authz) {
+      this.authentication = authz;
       return (SELF) this;
     }
 
@@ -162,7 +162,7 @@ private static boolean isWeaviateDomain(String host) {
     public Config build() {
       // For clusters hosted on Weaviate Cloud, Weaviate Embedding Service
       // will be available under the same domain.
-      if (isWeaviateDomain(httpHost) && authorization != null) {
+      if (isWeaviateDomain(httpHost) && authentication != null) {
         setHeader(HEADER_X_WEAVIATE_CLUSTER_URL, "https://" + httpHost + ":" + httpPort);
       }
       return new Config(this);
@@ -221,11 +221,11 @@ public Local grpcPort(int port) {
    * {@link #trustManagerFactory}.
    */
   public static class WeaviateCloud extends Builder<WeaviateCloud> {
-    public WeaviateCloud(String httpHost, Authorization authorization) {
-      this(URI.create(httpHost), authorization);
+    public WeaviateCloud(String httpHost, Authentication authentication) {
+      this(URI.create(httpHost), authentication);
     }
 
-    public WeaviateCloud(URI clusterUri, Authorization authorization) {
+    public WeaviateCloud(URI clusterUri, Authentication authentication) {
       scheme("https");
       super.httpHost(clusterUri.getHost() != null
           ? clusterUri.getHost() // https://[example.com]/about
@@ -233,7 +233,7 @@ public WeaviateCloud(URI clusterUri, Authorization authorization) {
       super.grpcHost("grpc-" + this.httpHost);
       this.httpPort = 443;
       this.grpcPort = 443;
-      this.authorization = authorization;
+      this.authentication = authentication;
     }
 
     /**
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
index 5450da135..956137ac2 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClient.java
@@ -27,13 +27,13 @@ public WeaviateClient(Config config) {
 
     RestTransportOptions restOpt;
     GrpcChannelOptions grpcOpt;
-    if (config.authorization() == null) {
+    if (config.authentication() == null) {
       restOpt = config.restTransportOptions();
       grpcOpt = config.grpcTransportOptions();
     } else {
       TokenProvider tokenProvider;
       try (final var noAuthRest = new DefaultRestTransport(config.restTransportOptions())) {
-        tokenProvider = config.authorization().getTokenProvider(noAuthRest);
+        tokenProvider = config.authentication().getTokenProvider(noAuthRest);
       } catch (Exception e) {
         // Generally exceptions are caught in TokenProvider internals.
         // This one may be thrown when noAuthRest transport is auto-closed.
@@ -111,7 +111,7 @@ public static WeaviateClient wcd(String httpHost, String apiKey) {
   /** Connect to a Weaviate Cloud instance. */
   public static WeaviateClient wcd(String httpHost, String apiKey,
       Function<Config.WeaviateCloud, ObjectBuilder<Config>> fn) {
-    var config = new Config.WeaviateCloud(httpHost, Authorization.apiKey(apiKey));
+    var config = new Config.WeaviateCloud(httpHost, Authentication.apiKey(apiKey));
     return new WeaviateClient(fn.apply(config).build());
   }
 
diff --git a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
index c78915ece..de9262881 100644
--- a/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
+++ b/src/main/java/io/weaviate/client6/v1/api/WeaviateClientAsync.java
@@ -21,19 +21,19 @@ public class WeaviateClientAsync implements AutoCloseable {
   public final WeaviateCollectionsClientAsync collections;
 
   /**
-   * This constructor is blocking if {@link Authorization} configured,
+   * This constructor is blocking if {@link Authentication} configured,
    * as the client will need to do the initial token exchange.
    */
   public WeaviateClientAsync(Config config) {
     RestTransportOptions restOpt;
     GrpcChannelOptions grpcOpt;
-    if (config.authorization() == null) {
+    if (config.authentication() == null) {
       restOpt = config.restTransportOptions();
       grpcOpt = config.grpcTransportOptions();
     } else {
       TokenProvider tokenProvider;
       try (final var noAuthRest = new DefaultRestTransport(config.restTransportOptions())) {
-        tokenProvider = config.authorization().getTokenProvider(noAuthRest);
+        tokenProvider = config.authentication().getTokenProvider(noAuthRest);
       } catch (Exception e) {
         // Generally IOExceptions are caught in TokenProvider internals.
         // This one may be thrown when noAuthRest transport is auto-closed.
@@ -53,7 +53,7 @@ public WeaviateClientAsync(Config config) {
    * Connect to a local Weaviate instance.
    *
    * <p>
-   * This call is blocking if {@link Authorization} configured,
+   * This call is blocking if {@link Authentication} configured,
    * as the client will need to do the initial token exchange.
    */
   public static WeaviateClientAsync local() {
@@ -64,7 +64,7 @@ public static WeaviateClientAsync local() {
    * Connect to a local Weaviate instance.
    *
    * <p>
-   * This call is blocking if {@link Authorization} configured,
+   * This call is blocking if {@link Authentication} configured,
    * as the client will need to do the initial token exchange.
    */
   public static WeaviateClientAsync local(Function<Config.Local, ObjectBuilder<Config>> fn) {
@@ -75,7 +75,7 @@ public static WeaviateClientAsync local(Function<Config.Local, ObjectBuilder<Con
    * Connect to a Weaviate Cloud instance.
    *
    * <p>
-   * This call is blocking if {@link Authorization} configured,
+   * This call is blocking if {@link Authentication} configured,
    * as the client will need to do the initial token exchange.
    */
   public static WeaviateClientAsync wcd(String httpHost, String apiKey) {
@@ -86,12 +86,12 @@ public static WeaviateClientAsync wcd(String httpHost, String apiKey) {
    * Connect to a Weaviate Cloud instance.
    *
    * <p>
-   * This call is blocking if {@link Authorization} configured,
+   * This call is blocking if {@link Authentication} configured,
    * as the client will need to do the initial token exchange.
    */
   public static WeaviateClientAsync wcd(String httpHost, String apiKey,
       Function<Config.WeaviateCloud, ObjectBuilder<Config>> fn) {
-    var config = new Config.WeaviateCloud(httpHost, Authorization.apiKey(apiKey));
+    var config = new Config.WeaviateCloud(httpHost, Authentication.apiKey(apiKey));
     return new WeaviateClientAsync(fn.apply(config).build());
   }
 
@@ -99,7 +99,7 @@ public static WeaviateClientAsync wcd(String httpHost, String apiKey,
    * Connect to a Weaviate instance with custom configuration.
    *
    * <p>
-   * This call is blocking if {@link Authorization} configured,
+   * This call is blocking if {@link Authentication} configured,
    * as the client will need to do the initial token exchange.
    */
   public static WeaviateClientAsync custom(Function<Config.Custom, ObjectBuilder<Config>> fn) {
diff --git a/src/test/java/io/weaviate/client6/v1/api/AuthorizationTest.java b/src/test/java/io/weaviate/client6/v1/api/AuthenticationTest.java
similarity index 93%
rename from src/test/java/io/weaviate/client6/v1/api/AuthorizationTest.java
rename to src/test/java/io/weaviate/client6/v1/api/AuthenticationTest.java
index 67a467ead..ea8531d48 100644
--- a/src/test/java/io/weaviate/client6/v1/api/AuthorizationTest.java
+++ b/src/test/java/io/weaviate/client6/v1/api/AuthenticationTest.java
@@ -15,7 +15,7 @@
 import io.weaviate.client6.v1.internal.rest.RestTransportOptions;
 import io.weaviate.client6.v1.internal.rest.SimpleEndpoint;
 
-public class AuthorizationTest {
+public class AuthenticationTest {
   private ClientAndServer mockServer;
   private RestTransport noAuthTransport;
 
@@ -37,8 +37,8 @@ public void startMockServer() throws IOException {
   }
 
   @Test
-  public void testAuthorization_apiKey() throws Exception {
-    var authz = Authorization.apiKey("my-api-key");
+  public void testAuthentication_apiKey() throws Exception {
+    var authz = Authentication.apiKey("my-api-key");
     var transportOptions = new RestTransportOptions(
         "http", "localhost", mockServer.getLocalPort(),
         Collections.emptyMap(), authz.getTokenProvider(noAuthTransport), null);

From 733bc7d2803156f56a56e5f78337ceaef210af3a Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Wed, 20 Aug 2025 13:00:07 +0200
Subject: [PATCH 29/31] chore: add comment

---
 .../client6/v1/internal/rest/AuthenticationInterceptor.java    | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java b/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
index 129c8c5de..f4a61a7ea 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/rest/AuthenticationInterceptor.java
@@ -52,6 +52,9 @@ public void process(HttpRequest request, EntityDetails entity, HttpContext conte
   public void execute(HttpRequest request, AsyncEntityProducer entityProducer, Scope scope, AsyncExecChain chain,
       AsyncExecCallback callback) throws HttpException, IOException {
 
+    // CloseableHttpClient is backed by an internal I/O reactor, which runs its own
+    // threads for non-blocking I/O. It does not expose that executor, so we must
+    // schedule CompletableFutures on the default AsyncTokenProvider's executor.
     tokenProviderAsync.getToken().whenComplete((tok, error) -> {
       if (error != null) {
         callback.failed(error instanceof Exception ex ? ex : new RuntimeException(error));

From 06661b95b2861782f0f4206d01e6a85bd0c4a748 Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Thu, 21 Aug 2025 19:48:24 +0200
Subject: [PATCH 30/31] feat: test that tokens are being refreshed after expiry

---
 .../java/io/weaviate/containers/Weaviate.java |  29 +++-
 .../integration/OIDCSupportITest.java         | 133 +++++++++++++-----
 .../v1/internal/BackgroundTokenProvider.java  |   1 -
 .../client6/v1/internal/TokenProvider.java    |   4 +-
 .../client6/v1/internal/TokenTest.java        |   7 +
 5 files changed, 132 insertions(+), 42 deletions(-)

diff --git a/src/it/java/io/weaviate/containers/Weaviate.java b/src/it/java/io/weaviate/containers/Weaviate.java
index 1a7da8e57..b906d5df8 100644
--- a/src/it/java/io/weaviate/containers/Weaviate.java
+++ b/src/it/java/io/weaviate/containers/Weaviate.java
@@ -25,9 +25,12 @@ public WeaviateClient getClient() {
   }
 
   /**
-   * Get a client for the current Weaviate container.
-   * As we aren't running tests in parallel at the moment,
-   * this is not made thread-safe.
+   * Create a new instance of WeaviateClient connected to this container if none
+   * exist. Get an existing client otherwise.
+   *
+   * The lifetime of this client is tied to that of its container, which means
+   * that you do not need to {@code close} it manually. It will only truly close
+   * after the parent Testcontainer is stopped.
    */
   public WeaviateClient getClient(Function<Config.Custom, ObjectBuilder<Config>> fn) {
     if (!isRunning()) {
@@ -58,6 +61,26 @@ public WeaviateClient getClient(Function<Config.Custom, ObjectBuilder<Config>> f
     return clientInstance;
   }
 
+  /**
+   * Create a new instance of WeaviateClient connected to this container.
+   * Prefer using {@link #getClient} unless your test needs the initialization
+   * steps to run, e.g. OIDC authorization grant exchange.
+   */
+  public WeaviateClient getNewClient(Function<Config.Custom, ObjectBuilder<Config>> fn) {
+    if (!isRunning()) {
+      start();
+    }
+    var host = getHost();
+    var customFn = ObjectBuilder.partial(fn,
+        conn -> conn
+            .scheme("http")
+            .httpHost(host)
+            .grpcHost(host)
+            .httpPort(getMappedPort(8080))
+            .grpcPort(getMappedPort(50051)));
+    return WeaviateClient.custom(customFn);
+  }
+
   public static Weaviate createDefault() {
     return new Builder().build();
   }
diff --git a/src/it/java/io/weaviate/integration/OIDCSupportITest.java b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
index 3a115649d..9b9a36691 100644
--- a/src/it/java/io/weaviate/integration/OIDCSupportITest.java
+++ b/src/it/java/io/weaviate/integration/OIDCSupportITest.java
@@ -23,6 +23,8 @@
  * Running this test suite successfully requires talking to external services,
  * so tests will be skipped if we don't have internet. See
  * {@link #hasInternetConnection}.
+ * Additionally, {@code WCS_DUMMY_CI_PW} and {@code OKTA_CLIENT_SECRET}
+ * environment variables must be set.
  */
 public class OIDCSupportITest extends ConcurrentTest {
   private static final String WCS_DUMMY_CI_USERNAME = "oidc-test-user@weaviate.io";
@@ -47,14 +49,31 @@ public class OIDCSupportITest extends ConcurrentTest {
       .withOIDC(OKTA_CLIENT_ID, "https://dev-32300990.okta.com/oauth2/aus7e9kxbwYQB0eht5d7", "cid", "groups")
       .build();
 
+  /**
+   * Exchange a Resource Owner Password grant for a bearer token
+   * and authenticate with it.
+   */
   @Test
   public void test_bearerToken() throws Exception {
     Assume.assumeTrue("WCS_DUMMY_CI_PW is not set", WCS_DUMMY_CI_PW != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
-    var t = SpyTokenProvider.stealToken();
-    var auth = Authentication.bearerToken(t.accessToken(), t.refreshToken(), t.expiresIn());
+    var passwordAuth = Authentication.resourceOwnerPassword(WCS_DUMMY_CI_USERNAME, WCS_DUMMY_CI_PW, List.of());
+    var t = SpyTokenProvider.stealToken(passwordAuth);
+    Assertions.assertThat(t.isValid()).as("bearer token is valid").isTrue();
+
+    // Expire this token immediately to force the client to fetch a new one.
+    var auth = SpyTokenProvider.spyOn(Authentication.bearerToken(t.accessToken(), t.refreshToken(), 0));
     pingWeaviate(wcsContainer, auth);
+
+    var newT = auth.getToken();
+    Assertions.assertThat(newT.accessToken())
+        .as("expect access_token was refreshed")
+        .isNotEqualTo(t.accessToken());
+
+    // Check that the new token authenticates requests.
+    pingWeaviate(wcsContainer, auth);
+    pingWeaviateAsync(wcsContainer, auth);
   }
 
   @Test
@@ -62,8 +81,24 @@ public void test_resourceOwnerPassword() throws Exception {
     Assume.assumeTrue("WCS_DUMMY_CI_PW is not set", WCS_DUMMY_CI_PW != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
-    var auth = Authentication.resourceOwnerPassword(WCS_DUMMY_CI_USERNAME, WCS_DUMMY_CI_PW, List.of());
+    // Check norwal resource owner password flow works.
+    var password = Authentication.resourceOwnerPassword(WCS_DUMMY_CI_USERNAME, WCS_DUMMY_CI_PW, List.of());
+    var auth = SpyTokenProvider.spyOn(password);
+    pingWeaviate(wcsContainer, auth);
+    pingWeaviateAsync(wcsContainer, auth);
+
+    // Get the token obtained by the wrapped TokenProvider.
+    var t = auth.getToken();
+
+    // Now make all tokens expire immediately, forcing the client to refresh..
+    // Verify the new token is different from the one before.
+    auth.setExpiresIn(0);
     pingWeaviate(wcsContainer, auth);
+
+    var newT = auth.getToken();
+    Assertions.assertThat(newT.accessToken())
+        .as("expect access_token was refreshed")
+        .isNotEqualTo(t.accessToken());
   }
 
   @Test
@@ -71,44 +106,55 @@ public void test_clientCredentials() throws Exception {
     Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
     Assume.assumeTrue("no internet connection", hasInternetConnection());
 
-    var auth = Authentication.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
+    // Check norwal client credentials flow works.
+    var cc = Authentication.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
+    var auth = SpyTokenProvider.spyOn(cc);
     pingWeaviate(oktaContainer, auth);
-  }
+    pingWeaviateAsync(oktaContainer, auth);
 
-  /**
-   * Test AuthenticationInterceptor (HTTP) / TokenCallCredentials (gRPC)
-   * work correctly in the async context.
-   */
-  @Test
-  public void test_clientCredentials_async() throws Exception {
-    Assume.assumeTrue("OKTA_CLIENT_SECRET is not set", OKTA_CLIENT_SECRET != null);
-    Assume.assumeTrue("no internet connection", hasInternetConnection());
+    // Get the token obtained by the wrapped TokenProvider.
+    var t = auth.getToken();
 
-    var auth = Authentication.clientCredentials(OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, List.of());
-    final var client = oktaContainer.getClient(conn -> conn.authentication(auth));
-    final var async = client.async();
+    // Now make all tokens expire immediately, forcing the client to refresh..
+    // Verify the new token is different from the one before.
+    auth.setExpiresIn(0);
+    pingWeaviate(oktaContainer, auth);
 
-    try {
-      // Make an authenticated REST call
-      Assertions.assertThat(async.isLive().get()).isTrue();
+    var newT = auth.getToken();
+    Assertions.assertThat(newT.accessToken())
+        .as("expect access_token was refreshed")
+        .isNotEqualTo(t.accessToken());
+  }
+
+  /** Send an HTTP and gRPC requests using a "sync" client. */
+  private static void pingWeaviate(final Weaviate container, Authentication auth) throws Exception {
+    try (final var client = container.getNewClient(conn -> conn.authentication(auth))) {
+      // Make an authenticated HTTP call
+      Assertions.assertThat(client.isLive()).isTrue();
 
       // Make an authenticated gRPC call
-      var nsThings = ns("Things");
-      async.collections.create(nsThings);
-      var things = async.collections.use(nsThings);
+      var nsThings = unique("Things");
+      client.collections.create(nsThings);
+      var things = client.collections.use(nsThings);
       var randomUuid = UUID.randomUUID().toString();
-      Assertions.assertThat(things.data.exists(randomUuid).get()).isFalse();
-    } catch (Exception e) {
-      Assertions.fail(e);
-    } finally {
-      client.close();
-      async.close();
+      Assertions.assertThat(things.data.exists(randomUuid)).isFalse();
     }
   }
 
-  private static void pingWeaviate(final Weaviate container, Authentication auth) throws Exception {
-    try (final var client = container.getClient(conn -> conn.authentication(auth))) {
-      Assertions.assertThat(client.isLive()).isTrue();
+  /** Send an HTTP and gRPC requests using an "async" client. */
+  private static void pingWeaviateAsync(final Weaviate container, Authentication auth) throws Exception {
+    try (final var client = container.getNewClient(conn -> conn.authentication(auth))) {
+      try (final var async = client.async()) {
+        // Make an authenticated HTTP call
+        Assertions.assertThat(async.isLive().join()).isTrue();
+
+        // Make an authenticated gRPC call
+        var nsThings = unique("Things");
+        async.collections.create(nsThings).join();
+        var things = async.collections.use(nsThings);
+        var randomUuid = UUID.randomUUID().toString();
+        Assertions.assertThat(things.data.exists(randomUuid).join()).isFalse();
+      }
     }
   }
 
@@ -132,14 +178,19 @@ private static boolean ping(String site) {
    */
   private static class SpyTokenProvider implements Authentication, TokenProvider {
 
-    /** Exchange resource owner password for a token and return it. */
-    static Token stealToken() throws Exception {
-      var auth = Authentication.resourceOwnerPassword(WCS_DUMMY_CI_USERNAME, WCS_DUMMY_CI_PW, List.of());
-      var spy = new SpyTokenProvider(auth);
+    /** Spy on the TokenProvider returned by thie Authentication. */
+    static SpyTokenProvider spyOn(Authentication auth) {
+      return new SpyTokenProvider(auth);
+    }
+
+    /** Spy a token obtained by another TokenProvider. */
+    static Token stealToken(Authentication auth) throws Exception {
+      var spy = spyOn(auth);
       pingWeaviate(wcsContainer, spy);
       return spy.getToken();
     }
 
+    private Long expiresIn;
     private Authentication authentication;
     private TokenProvider tokenProvider;
 
@@ -155,7 +206,17 @@ public TokenProvider getTokenProvider(RestTransport transport) {
 
     @Override
     public Token getToken() {
-      return tokenProvider.getToken();
+      var t = tokenProvider.getToken();
+      if (expiresIn != null) {
+        t = Token.expireAfter(t.accessToken(), t.refreshToken(), expiresIn);
+      }
+      return t;
     }
+
+    /** Expire all tokens in {@code expiresIn} seconds. */
+    void setExpiresIn(long expiresIn) {
+      this.expiresIn = expiresIn;
+    }
+
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/BackgroundTokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/BackgroundTokenProvider.java
index 4123952f7..2d95c480d 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/BackgroundTokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/BackgroundTokenProvider.java
@@ -56,7 +56,6 @@ private void scheduleNextRefresh() {
 
   @Override
   public void close() throws Exception {
-    System.out.println("BackgroundTokenProvider::close");
     exec.shutdown();
   }
 }
diff --git a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
index 397ad9a3a..fe565c345 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/TokenProvider.java
@@ -37,11 +37,11 @@ public boolean neverExpires() {
      * A Token with {@link #expiresIn} of 10s and {@link #expiryDelta} of 3s
      * will be invalid 7s after being created.
      *
-     * @param expiryDelta Early expiry in seconds.
+     * @param expiryDelta Early expiry in seconds. A negative value is clamped to 0.
      * @return A Token identical to the source one, but with a different expiry.
      */
     public Token withExpiryDelta(long expiryDelta) {
-      return new Token(accessToken, refreshToken, createdAt, expiresIn, expiryDelta);
+      return new Token(accessToken, refreshToken, createdAt, expiresIn, Math.max(0, expiryDelta));
     }
 
     /** Create a token with a different refresh_token. */
diff --git a/src/test/java/io/weaviate/client6/v1/internal/TokenTest.java b/src/test/java/io/weaviate/client6/v1/internal/TokenTest.java
index dd6cd7974..789ffca1a 100644
--- a/src/test/java/io/weaviate/client6/v1/internal/TokenTest.java
+++ b/src/test/java/io/weaviate/client6/v1/internal/TokenTest.java
@@ -33,4 +33,11 @@ public void test_isValid(Token token, boolean wantValid) {
         .as(token.toString())
         .isEqualTo(wantValid);
   }
+
+  @Test
+  public void test_expiryDeltaNonNegative() {
+    var t = Token.expireAfter("access_token", 90L);
+    var expireLater = t.withExpiryDelta(-10L);
+    Assertions.assertThat(expireLater.expiryDelta()).as("expiryDelta must be >= 0").isEqualTo(0L);
+  }
 }

From f5ef7752cb95fb77ffafcd41ed824ad040c8ac8e Mon Sep 17 00:00:00 2001
From: dyma solovei <dyma@weaviate.io>
Date: Fri, 22 Aug 2025 10:11:22 +0200
Subject: [PATCH 31/31] refactor: remove redundant variable

---
 .../client6/v1/internal/oidc/nimbus/HttpResponseParser.java    | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java
index e48e13402..3c7f70436 100644
--- a/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java
+++ b/src/main/java/io/weaviate/client6/v1/internal/oidc/nimbus/HttpResponseParser.java
@@ -52,8 +52,7 @@ static OIDCTokens parse(HTTPResponse httpResponse) throws ParseException {
 
     var error = fromErrorResponse(response.toErrorResponse());
     if (!error.isComplete()) {
-      var error2 = fromHttpResponse(httpResponse);
-      error = error2;
+      error = fromHttpResponse(httpResponse);
     }
     throw new WeaviateOAuthException("%s (code=%s)".formatted(
         error.description(),