Skip to main content

Documentation Index

Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt

Use this file to discover all available pages before exploring further.

The Authentication API authenticates users to use Lucidworks Platform APIs, including the Lucidworks AI APIs and Commerce Studio Rules and Rewrites API. The single endpoint generates an access token to use in future API requests.

​
Token guidelines and behavior

  • Lucidworks uses OAuth 2.0 to authenticate your credentials.
  • Tokens generated by the Authentication API are Java Web tokens (JWT) tokens.
  • Every token generated is active for 3600 seconds before it expires. After that token expires, API requests attempting to use the token fail and generate an HTTP status 401 Unauthorized error.
  • You can generate a new token at any time. To avoid authorization failures, generate a new token before the current token expires. For example, generate a new token five minutes before the current token expires.
    To calculate the token expiration time, Base64 decode the JWT and review the exp field, which contains the expiration time in seconds since the Unix epoch.

​
Authentication scope

You must specify one or more values for the scope of each authentication request. The values depend on which API you use:
ScopeUsed For
machinelearning.modelModels API
machinelearning.predictUse Case API, Prediction API, Async Prediction API, and Async Chunking API
commercestudio.rulesCommerce Studio rule operations (create, read, update, delete rules)
commercestudio.rewritesCommerce Studio query rewrite operations (create, read, update, delete rewrites)
Because the Use Case API, Prediction API, Async Prediction API, and Async Chunking API use the machinelearning.predict scope, if you request a new token with that scope, it deletes the existing token, so all of the APIs are affected. You need to manage token regeneration for those APIs to run successfully.

​
Fetch the access token

1

Locate your integration

In the Platform UI, navigate to Models > Integrations and click on your integration. To fetch an access token, you’ll need these details from your integration:
  • Client ID
  • Client secret
Learn more about integrations.
2

Compose your request

You’ll send your access token request using the Authentication API.The request uses basic authentication, where your base64-encoded client ID is your username and your base64-encoded client secret is your password. Some clients perform the encoding automatically; if not, you can use the base64 command line utility, like this:
echo -n "CLIENT_ID:CLIENT_SECRET" | base64
Compose your request like this:
curl --request POST \
  --url 'https://identity.lucidworks.com/oauth2/ausao8uveaPmyhv0v357/v1/token?scope=API_SCOPE&grant_type=client_credentials' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic [CLIENT_ID:CLIENT_SECRET_BASE64]' \
  --header 'Cache-Control: no-cache' \
  --header 'Content-Type: application/x-www-form-urlencoded'
The value of the scope query parameter varies between APIs, and you need a separate access token for each scope:
  • The Models API uses the machinelearning.model scope.
  • All other APIs use the machinelearning.predict scope.
3

Fetch the access token

When you send a successful Authentication API request, the JSON response looks like this:
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "ACCESS_TOKEN",
"scope": "API_SCOPE"
}
Copy the value of the access_token key and use it for API authentication.
4

Refresh your token every 60 minutes

API access tokens expire after 60 minutes.
Once you request a new token, the previous one is deleted even if it has not yet expired. All subsequent API calls must use the new token.