How do I obtain and use a short-lived API access token from Okta?

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

There are two types of API access token. The recommended and most secure option is to obtain a short-lived OAuth2.0-compliant token on demand from LUSID’s identity provider, Okta. (The less-secure alternative is a long-lived personal access token.) 

To obtain a short-lived API access token from Okta, you require:

• The username and password of a LUSID user account. Typically these are the credentials of a service user set up to own the application or service calling the LUSID API, but it can alternatively be the credentials of a personal user. In either case, these credentials are specified when the account is created.

• A client ID and client secret. See how to generate these.

• Okta’s dedicated token URL for your LUSID domain. See how to look this up.

To call the LUSID REST API directly:

1. Make a POST request to your dedicated Okta token URL, passing in the username, password, client ID and client secret, suitably encoded:

   curl -X POST <your-okta-token-url>
      -H "Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1"
      --data-urlencode grant_type="password"
      --data-urlencode username="<your-username>"
      --data-urlencode password="<your-password>"
      --data-urlencode scope="openid client groups"
      --data-urlencode client_id="<your-client-id>"
      --data-urlencode client_secret="<your-client-secret>"

   The response from Okta contains 2 tokens (actual data shortened for brevity):

   {
      "token_type": "Bearer",
      "expires_in": 3600,
      "access_token": "eyJraWQiOiJvZDFzeFk4WTlPalMyZ2dZT3VidVBYT2dRX0dURkcwZ1...wmlxPjh49DYeEuh_w4vt2Q",
      "scope": client groups openid",
      "id_token": "eyJraWQiOiJvZDFzeFk4WTlPalMyZ2dZT3VidVBYT2dzeFk4WTlPalMKi8...Mh66mG9j7zfyQxsp7UPC4J"
   }

2. Extract the first token, keyed access_token and ending wmlxPjh49DYeEuh_w4vt2Q in this example.

3. Supply this API access token as a Bearer token in the Authorization HTTP header of a call to the LUSID API, for example:

   curl -X GET https://<your-domain>.lusid.com/api/api/instruments 
      -H "Authorization: Bearer eyJraWQiOiJvZDFzeFk4WTlPalMyZ2dZT3VidVBYT2dRX0dURkcwZ1...wmlxPjh49DYeEuh_w4vt2Q"

Note the process of obtaining and using an API access token is different if you are using the LUSID SDK.