Product Selector

Fusion 5.9
    Fusion 5.9

    Authentication API

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

    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, and Async Prediction 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, and Async Prediction 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:

    1. Sign in to Lucidworks Platform.

    2. Click the Lucidworks AI app where you want to use embeds.

    3. Click the Integrations icon.

    4. Click the API tab. The values display in the Credentials section of the screen.

    Obtain the access token

    Create a cURL request using Stoplight

    1. Click the View API specification button on this page.

    2. For the:

      • Use Case API, Prediction API, or Async Prediction API, paste the credentials in the applicable fields and use the scope value of machinelearning.predict to generate an access token.

        Because the Use Case API, Prediction API, and Async Prediction 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.

      • Models API, paste the credentials in the applicable fields and use the scope value of machinelearning.model to generate an access token.

        This authentication displays as Basic within the developer documentation tools in order to include the OAuth 2.0 authentication token that is already included. To use the request in the specification viewer, send your HTTP requests with an Authorization header that contains the word Basic followed by a space and a Base64-encoded string CLIENT_ID:CLIENT_SECRET.

    Obtain a token using command line text

    A basic token request requires the scope field and value.

    Key Description

    scope

    The identifier that specifies the API.

    • For Use Case API, Prediction API, or Async Prediction API authentication, use the scope value of machinelearning.predict.

    • For Models API authentication, use the scope value of machinelearning.model.
    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, access a Base64 encoding tool and convert your CLIENT_ID:CLIENT_SECRET.

    Replace CLIENT_ID:CLIENT_SECRET with the value you converted in the Base64 encoding 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]' \
  --header 'Cache-Control: no-cache' \
  --header 'Content-Type: application/x-www-form-urlencoded'