StripeClientBuilder throws an exception with null apiKey

[delor]

Describe the bug

When initializing StripeClient using StripeClient.builder(), providing a null value for the API key via .setApiKey(null) is allowed by the builder's interface. However, calling .build() on this builder results in an IllegalArgumentException because a global API key is expected at build time.

In a multi-tenant environment, it's common to use a single StripeClient instance and provide the specific tenant's API key with each request using RequestOptions.builder().setApiKey("sk_..."). In such scenarios, a global API key for the StripeClient itself is not necessary and might even be undesirable.

Currently, the SDK mandates a non-null API key during StripeClient construction, even if RequestOptions will be used for every subsequent API call.

To Reproduce

Attempt to build a StripeClient with a null API key:

try {
    StripeClient client = StripeClient.builder()
        .setApiKey(null) // Explicitly setting null, or not calling setApiKey if it defaults to null internally and is checked
        .build();
    // Potentially make a call, though the build() itself might fail
    // CustomerCollection customers = client.customers().list(RequestOptions.builder().setApiKey("sk_test_specific_tenant").build());
} catch (Exception e) {
    e.printStackTrace(); // Observe the exception during build()
}

Expected behavior

It should be possible to construct a StripeClient instance without a globally configured API key (i.e., with apiKey being null or not set on the builder) if the intention is to always provide the API key per request via RequestOptions.

The StripeClient.build() method should not throw an exception if no global API key is provided, and the responsibility for providing the API key should then fall entirely on the RequestOptions for each API call. If an API call is made without an API key in RequestOptions (and no global key is set), then an exception at that point would be appropriate.

Code snippets

OS

macOS

Java version

Java 21

stripe-java version

29.0.0

API version

2025-03-31.basil

Additional context

StripeClientBuilder.setApiKey does handle null apiKey so I don't get it why it's not accepted when the client is build.

stripe-java/src/main/java/com/stripe/StripeClient.java

Lines 519 to 526 in d177cbc

	public StripeClientBuilder setApiKey(String apiKey) {
	if (apiKey == null) {
	this.authenticator = null;
	} else {
	this.authenticator = new BearerTokenAuthenticator(apiKey);
	}
	return this;
	}

[helenye-stripe]

Hi @delor! You can use an empty string or placeholder string to have an analogous effect to the one you suggested. However, could you tell us a bit more about using a null api key and setting per-request versus using multiple clients? We're open to changing this pattern in the future to better support possible use cases.

StripeClient client = StripeClient.builder()
        .setApiKey("")
        .build();

[delor]

I develop software to manage devices owned by our customers (tenants). Each client has its own Stripe account through which it collects payments from its devices. The service I work on receives the purchase information, checks to whom the device with which the purchase was made belongs, assigns a Stripe API key based on the owner of the device, and performs the corresponding query.

The application is written in Spring Boot so I have one StripeClient instance that I inject into the business logic and use RequestOptions to pass the API key before each request.

[prathmesh-stripe]

Thanks for sharing your use case with us. I'll keep this thread open in case other users are also facing the same issue and want to chime in and share their use cases.

[shyamuu1]

If you dont set apiKey to null and let lombok default property to null, do you still get the exception?

[prathmesh-stripe]

If you dont set apiKey to null and let lombok default property to null, do you still get the exception?

@shyamuu1 I believe so although I haven't tested this with Lombok. You can set the default value to an empty string("") and it should not throw an exception.