You can communicate with LUSID via a RESTful API.

In addition to interacting with the API directly, there is also a suite of SDKs which are open-source and available to assist in using the LUSID platform.

To be able to make calls to the API, either directly or via the SDKs, you will need to provide a bearer token with each of your requests in the form of an OAuth 2.0 access token.

Authenticating & Generating an Access Token

To generate an access token which allows you to interact with the LUSID API you must first authenticate via the identity provider of the LUSID domain that you are trying to access. In this case the default provider is Okta. There are two ways to do this once you have a User account for the relevant LUSID domain. 

Option 1: Personal Access Token via the LUSID Website

You can generate a personal access token via the LUSID website. Once you have generated this token you can make your first API call to LUSID by supplying it as a bearer token as shown in "Making Your First API Call to LUSID" below.

Option 2: OAuth2.0 Client Credentials Flow using the Password Grant

Alternatively, you can authenticate via Okta using the client credentials OAuth2.0 flow. For this approach you must have a user which has access to a LUSID Application. Combined with the username and password of your account this Application contains all the credentials that you need to obtain an access token.

You can read more about creating and accessing Applications in the tutorial here.

Once you have access to an Application you will be able to see the Application's:

  • Client Id
  • Secret
  • Token Url
  • Api Url



Using these credentials as well as your username and password you can make a call to Okta to retrieve an access token for LUSID. You will need to ensure that each parameter is appropriately URL encoded. You can see an example of this using cURL below. 

$ curl -X POST <Token Url> \
  -H "Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1" \
  --data-urlencode grant_type="password" \
  --data-urlencode username="<Username>" \
  --data-urlencode password="<Password>" \
  --data-urlencode scope="openid client groups" \
  --data-urlencode client_id="<Client Id>" \
  --data-urlencode client_secret="<Secret>"

Note: The "charset=ISO-8859-1" is only necessary if URL encoding your parameters with 
--data-urlencode via the cURL command as per the example above. 

Making Your First API Call to LUSID

Using your access token along with the API url found in the Application you can then make calls to LUSID. You can see an example of listing all Instruments in LUSID below (note that the $api_url does already contain "/api" so the final url will have "/api/api" in it, this is correct). 

$ curl -X GET <Api Url>/api/instruments?limit=100 \
-H "Authorization: Bearer <LUSID Access Token>"

Access Token Expiration

The access token generated via the Oauth2.0 client credentials flow is only valid for a limited time window. Currently this is 60 minutes, however in the near future this will be significantly reduced. 

You can generate a new access token by re-authenticating via Okta. Alternatively you can also make use of a refresh token which no longer requires you to provide your username and password with the authentication request. You can read more about generating a new access token via a refresh token here.

Conversely, the personal access tokens generated via the LUSID website are given an optional expiry date upon creation. 

Using the SDKs & Authentication

There are several actively maintained SDKs available. They are designed to make it easier to call the LUSID APIs.

With the SDKs the requests to Okta required to generate and refresh your access token are handled for you.

To ensure that the SDK has the credentials that it needs for these requests you can provide them via environment variables or in a secrets.json file.

Using Environment Variables

The SDK configuration can be supplied by setting the following environment variables. 


Using a secrets.json File

Alternatively, to supply the SDK configuration via a secrets.json file, create a secrets.json populated with the appropriate values using the structure below. Place it in the tests folder of the SDK that you are using.

Note: If using a secrets.json file with the ApiClientFactory in the Python SDK there is no need to URL encode your credentials. 

  "api" : {
    "apiUrl": "",
    "tokenUrl": "",
    "clientId": "",
    "clientSecret": "",
    "username": "",
    "password": "",
    "applicationName": ""   


SDK Languages

The SDKs are currently available in the following languages. For each language you will find a set of tutorials/tests that you can run to give you an idea of how to call LUSID using the SDK.



To install via the Python package manager pip:

$ pip install lusid-sdk

For further details on the Python SDK please refer to the GitHub repository:



Maven artifacts can be downloaded from the Open Source Software Repository Hosting (OSSRH) by adding the following to your pom.xml:

      <version>{SDK Version}</version>

For further details on the Java SDK please refer to the GitHub repository:



To install via the C# package manager NuGet:

$ dotnet add package Lusid.Sdk

For further details on the C# SDK please refer to the GitHub repository:



To install via the Node package manager npm:

$ npm install @finbourne/lusid

For further details on the Typescript/Javascript SDK please refer to the GitHub repository:

Access Permissions

Once you have access to LUSID please note that depending on the access roles and policies attached to your account you still may have no or limited access to some of LUSID's features and the data contained inside the LUSID access that you are trying to access. You can read more about access permissions here.