With each request to the LUSID API, either directly or via the SDKs, you must provide a bearer token in the form of an OAuth 2.0 access token.

The preferred way to do this is to use Okta to generate a time-limited token for you.

Note: If you can't use a time-limited Okta access token, then it is possible to use a long-lasting, pre-authenticated personal access token instead.

An Okta access token expires after 1 hour. Instead of going through the entire authentication flow every time your token expires, you can use a refresh token to generate a new access token when you need one.

Retrieving authorisation details

To generate a refresh token, you must pass in the authorisation details for your application. To retrieve these details:

  1. Browse to your LUSID homepage: https://<your-domain-name>
  2. From the left-hand menu, select Identity and Access > Applications:
  3. For the appropriate application, click the 'eye' button to view it:

You should see a screen showing application details like this (if not, contact your LUSID administrator, since you might not have the right permissions):

Generating a refresh token

You must first generate an access token in order to get authorisation to generate a refresh token. To do this, use a tool such as curl to make a POST request to your Okta tenant, ensuring the scope parameter includes the value offline_access.

In the example below, replace the <Your-*> values with appropriate real values taken from the application details window (above), plus your LUSID user name and password:

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

This request returns three tokens; copy the value for the second of these (in the middle), which is labelled refresh_token, for example:

"scope":"client offline_access groups openid","refresh_token":"NtnxqtRO0vPteiam9_96ZzBYPISnsZX-WVv5jBy8pRY"

Using the refresh token to generate an access token

Make a second POST request to the same Okta tenant. This time:

  • You do not send your client id, client secret, username and password in the clear; instead you send just your client id and client secret in the authorization header using basic authentication.
  • The grant_type has a value of refresh_token.
  • You send the refresh token you generated above in the body of the request.

For example:

This request returns a new access token that you can use in an API call.