Product Selector

Fusion 5.12
    Fusion 5.12

    Authentication API

    The Authentication API authenticates a user to use the Springboard Operations APIs. The single endpoint can generate an access token to use in future Operations 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.
    • An authentication request for a Query API token does not affect an existing Push API token.

    • An authentication request for a Push API token does not affect an existing Query API token.

    • You can request a token for the Query API and Push API at the same time by entering credentials and scope for both in the cURL request. A single token is generated and each API is linked to the information applicable to that API.

      The authentication request scope for the Query API is different than the scope for the Push API.
    • Springboard uses OAuth 2.0 to authenticate your credentials.

    Authentication API process

    To use the Authentication API, you need the following items:

    • Your Client ID, which is used for the Username value within the developer documentation tools. This is not the same as your Springboard login value.

    • Your Client Secret, which is used for the Password value within the developer documentation tools. This is not the same as your Springboard login value.

    To obtain the API credentials:

    1. Click the Integrations icon from the Applications UI sidebar.

    2. Click the APIs tab. The values are displayed on the screen.

    Obtain the access token

    Create a cURL request using Stoplight

    1. Click the View API specification button on this page and follow the instructions listed in the Authentication API documentation.

    2. For the:

      • Query API, paste the credentials in the applicable fields and use the scope value of connectedsearch.query to generate an access token.

      • Push API, paste the credentials in the applicable fields and use the scope value of datasource.push to generate an access token. For more information, see Push API.

        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 Query API authentication, use the scope value of connectedsearch.query.

    • For Push API authentication, use the scope value of datasource.push.

    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=datasource.push&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'