How do I use an API access token with the LUSID SDK?

Every call made to the LUSID API must be authorised by an API access token.

You can call the LUSID REST API directly, or perhaps more conveniently using the LUSID SDK (available in multiple languages and frameworks). The SDK has helper classes that automate the process of obtaining an API access token and refreshing it upon expiry.

To enable the SDK to obtain an API access token, you must pass in your LUSID username and password, client ID and client secret, and dedicated Okta token URL using one of the following methods.

Note: If you set environment variables and create a secrets file, LUSID prefers environment variables.

Using environment variables

You can store your LUSID username, password, client ID and client secret as environment variables and make them available to the SDK. To do this:

Sign in to the LUSID web app using the credentials of a LUSID administrator.
From the left-hand menu, select Identity and access > Applications.
On the Applications dashboard, click the View icon of an appropriate application. See how to create an application.
In the Export credentials area, make sure Env variables for either Linux or Windows is selected and copy the data to the clipboard:
Run the commands sequentially in an appropriate shell to set those environment variables, supplying the user's actual LUSID password instead of <password> for FBN_PASSWORD.

The following script demonstrates passing pre-set environment variables into the synchronous version of the LUSID Python SDK to automatically generate an API access token when calling the InstrumentsApi.list_instruments method:

# Setup:
import lusid, pprint
from lusid.extensions import SyncApiClientFactory

# Authenticate:
api_factory = SyncApiClientFactory()

# Build Instrument API and list first instrument:
instruments_api = api_factory.build(lusid.InstrumentsApi)
response = instruments_api.list_instruments(limit=1)
pprint.pprint(response.to_dict()["values"])

Note: For an example of using the asynchronous version of the SDK, see the Github readme.

Using a secrets file

You can store your LUSID username, password, client ID and client secret in a file on disk and make it available to the SDK. To do this:

Sign in to the LUSID web app using the credentials of a LUSID administrator.
From the left-hand menu, select Identity and access > Applications.
On the Applications dashboard, click the View icon for an appropriate application. See how to create an application.
In the Export credentials area, make sure Secrets file is selected and copy the data to the clipboard:
Paste the data into an appropriate local file, for example secrets.json, supplying your actual LUSID password instead of <password>.

Providing secrets.json is in the same directory, the following script demonstrates generating an API access token automatically using the synchronous version of the LUSID Python SDK when the InstrumentsApi.list_instruments method is called:

# Setup:
import lusid, pprint
from lusid.extensions import SyncApiClientFactory

# Authenticate:
api_factory = SyncApiClientFactory()

# Build Instrument API and list first instrument:
instruments_api = api_factory.build(lusid.InstrumentsApi)
response = instruments_api.list_instruments(limit=1)
pprint.pprint(response.to_dict()["values"])

Note: For an example of using the asynchronous version of the SDK, see the Github readme.

Note if secrets.json is not in the same directory, or has a different file name, you must specify a SecretsFileConfigurationLoader:

# Setup:
import lusid, pprint
from lusid.extensions import (
    SyncApiClientFactory,
    SecretsFileConfigurationLoader
)

# Authenticate:
secrets_path = "/path/to/secrets.json"
config_loaders=[
    SecretsFileConfigurationLoader(secrets_path)
]
api_factory = SyncApiClientFactory(config_loaders=config_loaders)

# Build Instrument API and list first instrument:
instruments_api = api_factory.build(lusid.InstrumentsApi)
response = instruments_api.list_instruments(limit=1)
pprint.pprint(response.to_dict()["values"])