---
title: "Installing or upgrading to v2 Java SDKs"
slug: "installing-or-upgrading-to-v2-java-sdks"
updated: 2026-06-22T07:51:37Z
published: 2026-06-22T07:51:37Z
canonical: "support.lusid.com/installing-or-upgrading-to-v2-java-sdks"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.lusid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing or upgrading to v2 Java SDKs

> [!WARNING]
> **Important**: This is not the [latest version](/v1/docs/installing-or-upgrading-to-the-v3-java-sdk). v2 SDKs are supported for now, but will be discontinued later in 2026.

You can install or upgrade to v2 of the following in Java 1.8+ environments:

- LUSID Java SDK
- Other Java SDKs in the [FINBOURNE platform](/v1/docs/understanding-all-the-applications-in-the-finbourne-platform), for example Drive, Scheduler and Luminesce.

Note the following:

- We strongly recommend pinning a SDK to an exact version to control when you take updates and make your builds repeatable.
- The `master`/`main` branch of a SDK may not always have the latest API version; there may, for example, also be `v2` or `v3` branches. We aim to keep `master`/`main` updated with the latest API version, but there may be some lead time while we deprecate older endpoints. Once we deprecate older API versions, the latest API version is moved to the `master`/`main` branch.

## Installing v2 LUSID Java SDK

You must first configure your project's `pom.xml` file to use [sonatype](https://oss.sonatype.org/) as a source for Java packages:

```xml
<repositories>
  <repository>
    <id>ossrh-SNAPSHOT</id>
    <name>OSSRH</name>
    <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
  <repository>
    <id>ossrh-release</id>
    <name>OSSRH</name>
    <url>https://oss.sonatype.org/content/repositories/releases/</url>
  </repository>
</repositories>
```

You can install v2 of the LUSID Java SDK from [GitHub](https://github.com/finbourne/lusid-sdk-java), or by adding the following to the dependencies section of your project's `pom.xml` file:

```xml
<dependency>
    <groupId>com.finbourne</groupId>
    <artifactId>lusid-sdk</artifactId>
    <version>[2.0,3.0)</version>
</dependency>
```

To authenticate for the first time, you must generate a client ID and secret and store them with the credentials of a valid LUSID user as either environment variables or in a secrets file. The LUSID Java SDK uses these credentials to obtain a short-lived API access token from FINBOURNE's identity provider (Okta) on demand. [More information](/v1/docs/authorising-an-application-or-service-to-call-the-lusid-api).

## ​Upgrading to v2 from an earlier version

You can upgrade from v1 to v2 of the LUSID Java SDK by adding the following to the dependencies section of your project's `pom.xml` file:

```xml
<dependency>
    <groupId>com.finbourne</groupId>
    <artifactId>lusid-sdk</artifactId>
    <version>[2.0,3.0)</version>
</dependency>
```

We recommend upgrading to v2 as soon as possible to ensure you have access to the latest features.

Note that you must upgrade all SDKs used in a particular process to v2 at the same time. A process that uses both the Scheduler and Drive SDKs, for example, must either use v1 of both SDKs *or* v2 of both SDKs; mixing major versions will lead to dependency conflicts.

***Users need to update their code to reflect the following v2 changes...***

### Prerequisites for v2

Built for the [Jakarta EE](https://jakarta.ee/) platform.

### Removal of snapshot repository source

We no longer publish snapshot versions of the LUSID Java SDK, so the snapshot repository source can be removed from the repositories section of your project's `pom.xml` file:

```xml
<repositories>
  <repository>
    <id>ossrh-release</id>
    <name>OSSRH</name>
    <url>https://oss.sonatype.org/content/repositories/releases/</url>
  </repository>
</repositories>
```

### Preview SDKs

This release discontinues publishing the LUSID Java Preview SDK, instead adding the Experimental and Beta lifecycle APIs to a single SDK. Note that making requests to Experimental and Beta APIs requires additional licences; for more details please [contact support](https://www.finbourne.com/contact).

### Changes to executing API calls and optional parameters

In v1 of the Java SDK, API methods contained every parameter, so adding optional parameters to endpoints introduced breaking changes to the SDK. In v2, getters and setters are provided for optional parameters to eliminate occurrences of these breaking changes going forward:

- Users need to modify all API calls to provide only required parameters in function calls, setting optional parameters using the provided getters and setters.
- API calls must now be executed using the `execute` or `executeAsync` methods.

For example, the `getPortfolio` endpoint has two required parameters (`scope` and `code`) and four optional parameters (`effectiveAt`, `asAt`, `propertyKeys` and `relationshipDefinitionIds`). A v1 call that might look like this...

```java
String scope = "your-portfolio-scope";
String code = "your-portfolio-code";
OffsetDateTime effectiveAt = OffsetDateTime.now();
OffsetDateTime asAt = OffsetDateTime.now();
List<String> propertyKeys = Arrays.asList();
List<String> relationshipDefinitionIds = null;
Portfolio result = apiInstance.getPortfolio(scope, code, effectiveAt, asAt, propertyKeys, relationshipDefinitionIds)
```

...must be updated to look as follows in v2:

```java
String scope = "your-portfolio-scope";
String code = "your-portfolio-code";
OffsetDateTime effectiveAt = OffsetDateTime.now();
OffsetDateTime asAt = OffsetDateTime.now();
List<String> propertyKeys = Arrays.asList();
Portfolio result = apiInstance.getPortfolio(scope, code)
                                                .effectiveAt(effectiveAt)
                                                .asAt(asAt) 
                                                .propertyKeys(propertyKeys)
                                                .execute();
```

Notice we can omit optional parameters we don't wish to provide a value for in v2 , such as `relationshipDefinitionIds`.

### `ApiClientBuilder` functionality changes to replace `HttpClientFactory`

- The `HttpClientFactory` class is removed. This was previously used to provide an `OkHttpClient` to the `ApiClientBuilder`, configuring proxy settings and timeouts. The `ApiClientBuilder` class now provides this functionality.
- The `ApiClientBuilder` no longer accepts arguments for setting default timeouts. Instead, it accepts an [OkHttpClient.Builder](https://square.github.io/okhttp/3.x/okhttp/okhttp3/OkHttpClient.Builder.html) which an `ApiClient` can be built from. Timeouts and many other settings can be configured on the `OkHttpClient.Builder`:

```java
OkHttpClient.Builder clientBuilder = new OkHttpClient.Builder();
clientBuilder.readTimeout(20, TimeUnit.SECONDS);
ApiClient client = apiClientBuilder.build(apiConfiguration, clientBuilder);
```

### `ApiConfiguration` requires PAT argument

The `ApiConfiguration` now additionally requires `personalAccessToken` as an argument. If you do not wish to use a personal access token, you can pass in `null`.

### Namespaces and classes renamed

The following namespaces and classes have been renamed:

- `import com.finbourne.lusid.utilities` becomes `import com.finbourne.lusid.extensions`.
- `Lusid.` class prefix in the extensions module becomes `Finbourne.`

## Installing v1 of the LUSID Java SDK

Please note v1 of the LUSID Java SDK is now discontinued, but if you *do* need to install it for any reason, you must first configure your project's `pom.xml` file to use [sonatype](https://oss.sonatype.org/) as a source for Java packages:

```xml
<repositories>
  <repository>
    <id>ossrh-SNAPSHOT</id>
    <name>OSSRH</name>
    <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
  <repository>
    <id>ossrh-release</id>
    <name>OSSRH</name>
    <url>https://oss.sonatype.org/content/repositories/releases/</url>
  </repository>
</repositories>
```

For v1 of the LUSID Java SDK, two packages are published:

- `lusid-sdk` contains only APIs with a [lifecycle status](/v1/docs/what-is-the-lusid-feature-release-lifecycle) of Production or Early Access. You can install it by adding the following to the dependencies section of your project's `pom.xml` file:

```xml
<dependency>
  <groupId>com.finbourne</groupId>
  <artifactId>lusid-sdk</artifactId>
  <version>[1.0,2.0)</version>
</dependency>
```
- `lusid-sdk-preview` contains additional APIs with a lifecycle status of Experimental or Beta. You can install it by adding the following to the dependencies section of your project's `pom.xml` file:

```xml
<dependency>
  <groupId>com.finbourne</groupId>
  <artifactId>lusid-sdk-preview</artifactId>
  <version>[1.0,2.0)</version>
</dependency>
```