Authentication

OAuth

ClearXP supports the OAuth 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.

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.

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:

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:

{
  "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 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:

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:

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

Basic Authentication is deprecated and we now recommend all third party applications upgrade to OAuth for improved security.

ClearXP supports the Basic Auth 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

A ClearXP customer representative will provide you with an API Key and API Secret suitable for the integration you're building.

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.

Example CURL

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

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