> ## 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.

# Authentication API

export const LwTemplate = ({title = "Key questions to get you started", icon = "sparkles", cta = "Powered by Agent Studio", linkHref = "https://lucidworks.com/demo/?utm_source=docs&utm_medium=referral&utm_campaign=docs_cta_ai"}) => {
  const [isLoaded, setIsLoaded] = useState(false);
  useEffect(() => {
    const timer = setTimeout(() => {
      setIsLoaded(true);
    }, 500);
    return () => clearTimeout(timer);
  }, []);
  return <div className="lw-template-container">
      <Card title={title} icon={icon}>
        {isLoaded && <span dangerouslySetInnerHTML={{
    __html: `<lw-template id="a029c1a9-28be-427e-b0e1-5d918920246a"></lw-template
            >`
  }} />}
        <Link href={linkHref} className="agent-studio-link text-left text-gray-600 gap-2 dark:text-gray-400 text-sm font-medium flex flex-row items-center hover:text-primary dark:hover:text-primary-light group-hover:text-primary group-hover:dark:text-primary-light">Powered by Lucidworks Agent Studio</Link>
      </Card>
    </div>;
};

[old doc.lw link]: https://doc.lucidworks.com/lw-platform/ai/oa96k5

[localhost link]: http://localhost:3000/docs/lw-platform/lw-platform/authentication-api

[mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-platform/authentication-api

The Authentication API authenticates users to use Lucidworks Platform APIs, including the [Lucidworks AI APIs](/docs/lw-platform/lw-ai/lw-ai-apis/overview) and [Commerce Studio Rules and Rewrites API](/docs/lw-platform/lw-cs/cs-rules-rewrites-api).
The single endpoint generates an access token to use in future API requests.

<LwTemplate />

## 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](https://jwt.io/).
* 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.

  <Note>  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.</Note>

## Authentication scope

You must specify one or more values for the `scope` of each authentication request.
The values depend on which API you use:

| Scope | Used For |
| - | - |
| `machinelearning.predict` | Use Case API, Prediction API, Async Prediction API, and Async Chunking API |
| `commercestudio.rules` | Commerce Studio rule operations (create, read, update, delete rules) |
| `commercestudio.rewrites` | Commerce Studio query rewrite operations (create, read, update, delete rewrites) |

<Warning>
  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.
</Warning>

## Fetch the access token

<Accordion title="Fetch an access token" icon="key">
  <Steps>
    <Step title="Locate your client ID and secret">
      Where you find the client ID and secret depends on which API you're using:

      * For [Lucidworks AI APIs](/docs/lw-platform/lw-ai/lw-ai-apis/overview), go to **Models** > **Integrations** and click your integration, then copy the **Client ID** and **Client Secret**. [Learn more about Lucidworks AI integrations](/docs/lw-platform/lw-ai/integrations).

      * For [Commerce Studio APIs](/docs/lw-platform/lw-cs/cs-rules-rewrites-api), go to **Settings** > **Service Accounts** and click your service account, then copy the **Client ID** and **Client Secret**. [Learn how to create a service account](/docs/lw-platform/lw-cs/cs-rules-rewrites-api#create-a-service-account).
    </Step>

    <Step title="Compose your request">
      Send your access token request to the authentication endpoint.

      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:

      ```bash theme={"dark"}
      echo -n "CLIENT_ID:CLIENT_SECRET" | base64
      ```

      Compose your request like this:

      ```bash theme={"dark"}
      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'
      ```

      Set the `scope` query parameter to the value for your API, as listed in [Authentication scope](#authentication-scope).
    </Step>

    <Step title="Fetch the access token">
      A successful request returns:

      ```json theme={"dark"}
      {
      "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.
    </Step>

    <Step title="Refresh your token every 60 minutes">
      API access tokens expire after 60 minutes.

      <Warning>
        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.
      </Warning>
    </Step>
  </Steps>
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.