# Authentication

### OAuth

ClearXP supports the [**OAuth Authorization Code**](https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/) flow to allow third-party server-side applications to make requests on behalf of a user. This flow includes the following steps:

1. Your app will make a request to `/auth/oauth/authorize`
2. Log into your ClearXP admin account to authorise the integration. The webpage will redirect back to your server with a single-use `code` .
3. A request can be made to `/auth/oauth/token` to exchange the `code` for an `access_token` and `refresh_token` 
4. The `access_token` can now be used to make requests to the ClearXP API.

These steps will be outlined in more detail below.

{% hint style="info" %}
A **ClearXP** customer representative will provide you with a *Tenant Name*, *Client ID* and *Client Secret* suitable for the integration you're building. You will need to supply a *Redirect URI* which will be the location of your server that will receive the authentication tokens.

Please contact support if you need assistance.
{% endhint %}

#### **Step 1: Make Authorize Request**

Your server should make a full page request to the following URL:

```
https://auth.clearxp.com/auth/oauth/authorize
 ?client_id={YOUR_CLIENT_ID}
 &redirect_uri={YOUR_REDIRECT_URI}
 &response_type=code
```

This will load ClearXP's authentication screen.

#### **Step 2: Log into ClearXP**

You will need to log into an admin account with appropriate permissions to authorise the integration. Once done, the browser will redirect back to `YOUR_REDIRECT_URI`  and append a `code` query parameter that will be used in the next step.

The `code` is a single-use token that can be exchanged for an `access_token`  that can be used to authenticate API requests. The `code` expires after 10 minutes so should be exchanged immediately.

#### Step 3: Exchange Code

After receiving the request to `YOUR_REDIRECT_URI` , your server will need to read the `code`  query parameter and include it in the following back-end request:

```sh
curl -X POST https://auth.clearxp.com/auth/oauth/token \
  -H "content-type: application/json" \
  --data-binary @- << EOF
{
  "grant_type": "authorization_code",
  "client_id": "{YOUR_CLIENT_ID}",
  "client_secret": "{YOUR_CLIENT_SECRET}",
  "redirect_uri": "{YOUR_REDIRECT_URI}",
  "code": "{YOUR_CODE}"
}
EOF
```

If all parameters are valid, you will receive a response that looks like the following:

```json
{
  "access_token": "cxa_17CVaMDQnxWGOZNBbmTIrbHByJhBaPv4z",
  "refresh_token": "cxr_17CVaN0APukeYoEi7wVH3GQRlqhAjeUre",
  "token_type": "bearer",
  "expires_in": 3600
}
```

Note that the `access_token` can be used to make requests to the ClearXP API but expires after an hour. A new token can be issued by using the `refresh_token` (see [**Extending Access Token**](#extending-access-token) below).

#### Step 4: Make API Requests

From your server-side application, you can now make API requests using your `access_token` . This should include the token you've just received as well as your tenant ID:

```bash
curl -X POST https://clearlrs.com/api/import/users \
  -H "content-type: application/json" \
  -H "authorization: Bearer {YOUR_ACCESS_TOKEN}" \
  -H "X-CXP-Tenant: {YOUR_TENANT_NAME}"
```

#### Extending Access Token

Since access tokens expire after 1 hour, you will either need to reauthenticate the user for further requests or generate a new `access_token` using the `refresh_token` . This can be done by calling the following endpoint from your server-side application:

```bash
curl -X POST https://auth.clearxp.com/auth/oauth/token \
  -H "content-type: application/json" \
  --data-binary @- << EOF
{
  "grant_type": "refresh_token",
  "client_id": "{YOUR_CLIENT_ID}",
  "client_secret": "{YOUR_CLIENT_SECRET}",
  "refresh_token": "{YOUR_REFRESH_CODE}"
}
EOF
```

For long-lived integrations, you may need to periodically refresh the `access_token` using an automated task to keep the integration alive.

### Basic Authentication

{% hint style="danger" %}
**Basic Authentication** is deprecated and we now recommend all third party applications upgrade to [**OAuth**](#oauth) for improved security.
{% endhint %}

ClearXP supports the [**Basic Auth**](https://en.wikipedia.org/wiki/Basic_access_authentication) header when authenticating HTTP requests. If using a client library for building the authentication header, you will need to enter the following as the username and password for the request:

* **Username:** Your API Key
* **Password:** Your API Secret

{% hint style="info" %}
A **ClearXP** customer representative will provide you with an *API Key* and *API Secret* suitable for the integration you're building.
{% endhint %}

If building the HTTP request by hand, you will need to follow the Basic Auth specification to convert your username and password to a token that can be sent within the **authorization** HTTP header.

{% code title="Example CURL" %}

```bash
curl https://org.clearlrs.com/xapi/statements \
  -H "authorization: Basic a2V5OnNlY3JldA=="
```

{% endcode %}

In the above example, the token is a base64 encoding of `key:secret`

When content is launched from the LRS, a short-lived **token** will be automatically generated and supplied for the learner that launched the content. This **token** should be used as the value for the **authorization** header as demonstrated above. Read more about this mechanism in the [**Content Launch**](/getting-started/content-launch.md) section.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.clearxp.com/getting-started/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.