# 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**](https://dev.clearxp.com/getting-started/content-launch) section.