Authentication API

Table of Contents

Token guidelines and behavior
Authentication API process
Obtain the access token

The Authentication API authenticates a user to use the APIs. The single endpoint generates an access token to use in future API requests.

To view the full configuration specification for an API, click the View API specification button.

view api spec

Alternatively, click here to open the API spec.

Token guidelines and behavior

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.

The scope for the:

Models API is machinelearning.model.

Use Case API, Prediction API, Async Prediction API, and Async Chunking API is the same and is machinelearning.predict. Therefore, an authentication request for a token for these APIs does not affect an existing Models API token.

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.

Lucidworks uses OAuth 2.0 to authenticate your credentials.

Authentication API process

To use the Authentication API, you need the Client ID and Client Secret.

To obtain the API credentials:

Sign in to Lucidworks Platform.
Click Products and then click the Lucidworks AI app.
Click the Integrations icon.
Click the API tab. The values display in the Credentials section of the screen.

Obtain the access token

A basic token request requires the scope field and value. Refer to the API spec for more information.

Based on the Token guidelines and behavior, you must renew the current access token every hour before the 60-minute maximum expires.

To obtain or renew an access token, encode your CLIENT_ID:CLIENT_SECRET into Base64:

echo -n "CLIENT_ID:CLIENT_SECRET" | base64

Copy the following CURL command, replacing CLIENT_ID:CLIENT_SECRET_BASE64 with the value you encoded. Paste and run in your command line tool.

curl --request POST \
  --url 'https://identity.lucidworks.com/oauth2/ausao8uveaPmyhv0v357/v1/token?scope=machinelearning.predict&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'

If you request a new token with the machinelearning.predict scope, the existing token is deleted, and all APIs using that scope are affected. You need to manage token regeneration for those APIs to run successfully.