---
title: "Installing or upgrading to the v3 Java SDK"
slug: "installing-or-upgrading-to-the-v3-java-sdk"
updated: 2026-06-22T07:56:09Z
published: 2026-06-22T07:56:09Z
canonical: "support.lusid.com/installing-or-upgrading-to-the-v3-java-sdk"
stale: true
---
> ## 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 the v3 Java SDK
> [!WARNING]
> **Important**: This is the latest version. Information about older versions can be found [here](/v1/docs/installing-or-upgrading-to-v2-java-sdks).
The v3 Java SDK is a universal SDK that provides access to LUSID and to all the other applications in the [FINBOURNE platform](https://support.lusid.com/v1/docs/understanding-all-the-applications-in-the-finbourne-platform) from a single Maven artifact in Java 21+ environments.
You no longer need to declare and authenticate to separate per-service SDK dependencies to integrate LUSID with applications such as Drive, Workflow Service, Luminese and so on.
## Installation
To get started, add the following to the `<dependencies>` section of your project's `pom.xml` file:
```xml
com.finbourne.sdk
finbourne.sdk
LATEST
```
Note the following:
- Replace `<version>LATEST</version>` above with a valid [version number](https://github.com/finbourne/finbourne-sdk-java#installation), for example `<version>0.0.8</version>`.
- Java 21 or later is required.
- Alternatively, you can download the source by cloning the [GitHub repository](https://github.com/finbourne/finbourne-sdk-java).
## Import statements
Import from `com.finbourne.sdk.extensions` for factory and authentication classes, and from `com.finbourne.sdk.services.<service>` for the API endpoints and models of each FINBOURNE application you intend to use:
```java
// Factory and extensions:
import com.finbourne.sdk.extensions.ApiFactory;
import com.finbourne.sdk.extensions.ApiFactoryBuilder;
import com.finbourne.sdk.core.config.ApiConfigurationException;
import com.finbourne.sdk.core.config.ConfigurationOptions;
import com.finbourne.sdk.core.auth.FinbourneTokenException;
import com.finbourne.sdk.ApiException;
// To use LUSID:
import com.finbourne.sdk.services.lusid.api.PortfoliosApi;
import com.finbourne.sdk.services.lusid.api.TransactionPortfoliosApi;
import com.finbourne.sdk.services.lusid.model.Portfolio;
import com.finbourne.sdk.services.lusid.model.CreateTransactionPortfolioRequest;
// To use Drive:
import com.finbourne.sdk.services.drive.api.FilesApi;
// To use Identity:
import com.finbourne.sdk.services.identity.api.RolesApi;
```
## Authentication
The most secure method is OAuth2. If you haven't already, [create an SDK application](https://support.lusid.com/v1/docs/how-do-i-generate-and-reveal-a-client-secret) encapsulating a client ID, secret, and token URL, and store them with the credentials of a valid LUSID user as either environment variables or in a secrets file. The SDK uses these credentials to obtain a short-lived access token from FINBOURNE's identity provider (Okta) on demand, and refreshes it automatically.
> **Note**: If environment variables are set, they are preferred over a secrets file. [More information](/v1/docs/how-do-i-use-an-api-access-token-with-the-lusid-sdk).
You *can* use a long-lived [personal access token](https://support.lusid.com/v1/docs/what-is-a-personal-access-token) (PAT) instead of OAuth2, but note this is less secure.
### Using environment variables
All applications share a `FBN_BASE_URL` pointing to the root of your LUSID domain, for example `acme-prod.lusid.com`:
```shell
# OAuth2 (more secure):
FBN_BASE_URL=https://acme-prod.lusid.com
FBN_TOKEN_URL=https://acme-prod.identity.lusid.com/oauth2/.../v1/token
FBN_USERNAME=...
FBN_PASSWORD=...
FBN_CLIENT_ID=...
FBN_CLIENT_SECRET=...
# PAT:
FBN_BASE_URL=https://acme-prod.lusid.com
FBN_ACCESS_TOKEN=...
```
### Using a secrets file
A secrets file is a JSON document containing named profiles, one per LUSID domain you wish to connect to. The file must have at least one `default` profile. You can [switch between profiles](/v1/docs/installing-or-upgrading-to-the-v3-java-sdk#instantiation) at build time to connect to different domains.
The following example has two profiles: `default` connects to `acme-prod.lusid.com` using OAuth2, and `staging` connects to `acme-sit.lusid.com` using a PAT:
```json
{
"profiles": {
"default": {
"tokenUrl": "https://acme-prod.identity.lusid.com/oauth2/.../v1/token",
"baseUrl": "https://acme-prod.lusid.com",
"username": "...",
"password": "...",
"clientId": "...",
"clientSecret": "..."
},
"staging": {
"baseUrl": "https://acme-sit.lusid.com",
"accessToken": "..."
}
}
}
```
The active profile is determined in the following order:
1. The `FBN_PROFILE` environment variable, if set.
2. The `withProfileName()` parameter when you build the factory, if specified (see below).
3. The `default` profile.
## Instantiation
Build an `ApiFactory` using `ApiFactoryBuilder`, then call `build()` for each API class you want to use. API instances are cached per factory, so calling `build()` with the same class always returns the same instance.
If you are using environment variables you can omit `withConfigurationFile()`. If you are using a secrets file, you can optionally call `withProfileName()` to connect to a particular domain dynamically.
### Synchronous calls
```java
ApiFactory factory = new ApiFactoryBuilder()
.withConfigurationFile("secrets.json")
.withProfileName("staging") // optional
.build();
// Build the API instances you need:
TransactionPortfoliosApi transactionPortfoliosApi = factory.build(TransactionPortfoliosApi.class);
PortfoliosApi portfoliosApi = factory.build(PortfoliosApi.class);
FilesApi filesApi = factory.build(FilesApi.class);
// Call methods:
ResourceListOfPortfolio portfolios = portfoliosApi.listPortfoliosForScope("my-scope")
.effectiveAt("2024-01-01")
.limit(10)
.execute();
```
### Asynchronous calls
`executeAsync()` returns immediately and runs the request on a background thread via an `ApiCallback`. Bridge the callback to a `CompletableFuture` to compose on the result asynchronously, and only block at shutdown if necessary to prevent a short-lived program from exiting before the response arrives.
```java
import com.finbourne.sdk.ApiCallback;
import com.finbourne.sdk.services.lusid.api.ApplicationMetadataApi;
import com.finbourne.sdk.services.lusid.model.VersionSummaryDto;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
ApplicationMetadataApi metadataApi = factory.build(ApplicationMetadataApi.class);
CompletableFuture future = new CompletableFuture<>();
metadataApi.getLusidVersions().executeAsync(new ApiCallback<>() {
@Override
public void onSuccess(VersionSummaryDto result, int statusCode, Map> headers) {
future.complete(result);
}
@Override
public void onFailure(ApiException e, int statusCode, Map> headers) {
future.completeExceptionally(e);
}
@Override public void onUploadProgress(long bytesWritten, long contentLength, boolean done) {}
@Override public void onDownloadProgress(long bytesRead, long contentLength, boolean done) {}
});
future.thenAccept(version -> System.out.println("LUSID API version: " + version.getApiVersion()))
.exceptionally(error -> { System.err.println("Failed: " + error.getMessage()); return null; });
// Block at shutdown only:
future.join();
```
### Configuration options
You can optionally configure timeout and retry settings using `ConfigurationOptions`, either globally at factory level or as overrides per individual API call:
```java
// Set globally at factory level:
ConfigurationOptions opts = new ConfigurationOptions(
30000, // totalTimeoutMs
5000, // connectTimeoutMs
5000, // readTimeoutMs
5000, // writeTimeoutMs
5 // rateLimitRetries
);
ApiFactory factory = new ApiFactoryBuilder()
.withConfigurationFile("secrets.json")
.withConfigurationOptions(opts)
.build();
// Override per API call:
ConfigurationOptions callOpts = new ConfigurationOptions();
callOpts.setTotalTimeoutMs(60000);
callOpts.addHeader("X-Request-Id", "abc-123");
Portfolio portfolio = portfoliosApi.getPortfolio("scope", "code")
.execute(callOpts);
```
Default headers for all requests can also be set at factory level:
```java
ApiFactory factory = new ApiFactoryBuilder()
.withConfigurationFile("secrets.json")
.withHeaders(Map.of("X-Correlation-Id", "session-1"))
.build();
```
## Hello world
The following example authenticates using a secrets file, creates a transaction portfolio, reads it back, and cleans up:
```java
import com.finbourne.sdk.ApiException;
import com.finbourne.sdk.core.config.ApiConfigurationException;
import com.finbourne.sdk.core.config.ConfigurationOptions;
import com.finbourne.sdk.core.auth.FinbourneTokenException;
import com.finbourne.sdk.extensions.ApiFactory;
import com.finbourne.sdk.extensions.ApiFactoryBuilder;
import com.finbourne.sdk.services.lusid.api.PortfoliosApi;
import com.finbourne.sdk.services.lusid.api.TransactionPortfoliosApi;
import com.finbourne.sdk.services.lusid.model.CreateTransactionPortfolioRequest;
import com.finbourne.sdk.services.lusid.model.Portfolio;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;
public class Example {
public static void main(String[] args)
throws ApiConfigurationException, FinbourneTokenException, ApiException {
// 1. Build one factory for every service.
ApiFactory factory = new ApiFactoryBuilder()
.withConfigurationFile("secrets.json")
.build();
// 2. Build the API instances you need.
TransactionPortfoliosApi transactionPortfoliosApi = factory.build(TransactionPortfoliosApi.class);
PortfoliosApi portfoliosApi = factory.build(PortfoliosApi.class);
String scope = "examples";
String code = "example-portfolio";
// Optional: per-request timeout override.
ConfigurationOptions opts = new ConfigurationOptions();
opts.setTotalTimeoutMs(180_000);
// 3. Create a transaction portfolio.
CreateTransactionPortfolioRequest request = new CreateTransactionPortfolioRequest()
.code(code)
.displayName("Example portfolio")
.baseCurrency("USD")
.created(OffsetDateTime.of(2024, 1, 1, 0, 0, 0, 0, ZoneOffset.UTC));
try {
Portfolio created = transactionPortfoliosApi.createPortfolio(scope, request)
.execute(opts);
System.out.println("Created portfolio: " + created.getId().getCode());
// 4. Read it back. Required params in the method, optionals as chained setters.
Portfolio fetched = portfoliosApi.getPortfolio(scope, code)
.effectiveAt("2024-01-01")
.execute();
System.out.println("Base currency: " + fetched.getBaseCurrency());
} catch (ApiException e) {
System.err.println("Request failed (" + e.getCode() + "): " + e.getResponseBody());
} finally {
// 5. Clean up.
portfoliosApi.deletePortfolio(scope, code).execute();
}
}
}
```
For more information on FINBOURNE APIs, start with the articles in this KB, our [API sandbox](https://support.lusid.com/v1/docs/getting-started-with-the-lusid-rest-api-and-sdks), and library of [Jupyter Notebooks](https://github.com/finbourne/finbourne-notebooks).
## Appendix A: Migration checklist
The fluent request-builder calling style introduced in v2 is unchanged in v3, so the migration is mostly about packaging, dependencies, and configuration rather than rewriting call sites.
- **Replace per-service dependencies with a single artifact.** Remove all `com.finbourne:<service>-sdk` and `com.finbourne:<service>-sdk-extensions` dependencies from your `pom.xml` and replace them with the single `com.finbourne.sdk:finbourne.sdk` dependency.
- **Update package imports.** Replace `com.finbourne.lusid.api.*` and `com.finbourne.lusid.model.*` with `com.finbourne.sdk.services.lusid.api.*` and `com.finbourne.sdk.services.lusid.model.*` (and likewise for every other service). Update extensions imports from `com.finbourne.lusid.extensions` to `com.finbourne.sdk.extensions`.
- **Replace per-service factories with one** `ApiFactory`**.** Replace `LusidApiFactory`/`LusidApiFactoryBuilder` (and equivalents for other services) with `com.finbourne.sdk.extensions.ApiFactory`/`ApiFactoryBuilder`.
- **Update your secrets file.** Rename the `apiUrl` key to `baseUrl` and ensure the value points to the root of your domain.
- **Update environment variables.** Replace per-service variables such as `FBN_LUSID_API_URL` with `FBN_BASE_URL`, pointing to the root of your domain.
- **Upgrade your Java runtime to 21+.** v2 compiled to Java 1.8; v3 requires Java 21 or later.
- **Update JSON handling.** v2 used Gson; v3 uses Jackson 2.18.6. Update any code that relies on Gson annotations or type adapters from the model classes.
- **Remove** `jakarta.annotation` *if explicitly declared***.** v3 no longer depends on `jakarta.annotation-api`.
## Appendix B: Environment variable reference
| `FBN_BASE_URL` | Root of the LUSID domain to connect to |
| --- | --- |
| `FBN_TOKEN_URL` | Okta token URL for OAuth2 flow |
| `FBN_USERNAME` | LUSID username for OAuth2 flow |
| `FBN_PASSWORD` | LUSID user password for OAuth2 flow |
| `FBN_CLIENT_ID` | Client ID for OAuth2 flow |
| `FBN_CLIENT_SECRET` | Client secret for OAuth2 flow |
| `FBN_ACCESS_TOKEN` | Personal access token (less secure than OAuth2) |
| `FBN_PROFILE` | Sets the active profile in a `secrets.json` file |
| `FBN_TOTAL_TIMEOUT_MS` | Total timeout configuration option |
| `FBN_CONNECT_TIMEOUT_MS` | Authentication timeout configuration option |
| `FBN_READ_TIMEOUT_MS` | Read timeout configuration option |
| `FBN_WRITE_TIMEOUT_MS` | Write timeout configuration option |
| `FBN_RATE_LIMIT_RETRIES` | Rate limit retries configuration option |