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:
- Browse to your LUSID homepage: https://<your-domain-name>.lusid.com/
- From the left-hand menu, select Identity and Access > Applications:
- 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.
This request returns a new access token that you can use in an API call.