Getting started with the LUSID API and SDKs

Learn how to interact with the LUSID API using the SDKs and generate your client secrets file

Introduction

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.

To authenticate via Okta you must have either created or been provided 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

applications page

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 can see an example of this using cURL below. 

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

Using this 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 $access_token"

Access Token Expiration

The access token generated via this process 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.

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. 

Screen Shot 2019-08-04 at 4.42.49 pm

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.

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

Screen Shot 2019-08-04 at 5.17.54 pm

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.

 

Python

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:
https://github.com/finbourne/lusid-sdk-python

 

Java

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

<project>
...
<dependencies>
...
<dependency>
<groupId>com.finbourne</groupId>
<artifactId>lusid-sdk</artifactId>
<version>{SDK Version}</version>
</dependency>
...
</dependencies>
...
</project>

For further details on the Java SDK please refer to the GitHub repository:
https://github.com/finbourne/lusid-sdk-java

 

C#

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:
https://github.com/finbourne/lusid-sdk-csharp

 

Typescript/Javascript

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:
https://github.com/finbourne/lusid-sdk-js

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.