Account Provisioning and Launch

The system contains multiple built-in mechanisms for automatically provisioning user accounts inside the ClearXP platform, such as:

• Manually by admin creation or CSV import.

• Via an external data feed (either file import or API hooks).

• On-demand during Single-Sign-On.

However, if none of these suit, this guide will outline a way for third parties to build their own account provisioning and content launch integration.

The following guide requires a third-party Service Account for authentication of all API requests. Please contact our support team for assistance.

1. Account Provisioning

A valid xAPI Actor must exist in the system prior to content being launched. The following endpoint can be used to insert a new agent or update an existing agent.

PUT /api/actors/agents

curl -X POST "https://example.clearlrs.com/api/actors/agents" -H "authorization: API_TOKEN" -H "content-type: application/json" -i --data-binary @- << EOF
{
  "name": "User's Name",
  "account": {
    "homePage": "https://example.com",
    "name": "account-name"
  },
  "extensions": {
    "http://clearlrs.com/api/ext/agent/attributes": {
      "Country": "AU"
    }
  }
}
EOF

Because the agent is being provisioned on-the-fly, the account details must be generated by the system making the API request. The account homePage field may remain consistent for all users but it is recommended that an opaque but repeatable account name is used – potentially an internal ID, hash of the user's email address or similar.

The extensions.http://clearlrs.com/api/ext/agent/attributes field may contain any arbitrary user attributes that may be helpful for reporting purposes. If you include a unique identifier then the system will match any existing account in the system and return that actor instead.

2. Credential Generation

After the account has been created, an authentication token must be generated on behalf of the user that can be used to retrieve content and store tracking data in the system.

POST /api/auth/basic

curl -X POST "https://example.clearlrs.com/api/auth/basic" -H "authorization: API_TOKEN" -H "content-type: application/json" -i --data-binary @- << EOF
{
  "username": "RANDOM_KEY",
  "password": "RANDOM_SECRET",
  "data": {
    "actor": {
      "account": {
        "homePage": "https://example.com",
        "name": "account-name"
      }
    }
  }
}
EOF

The username and password values must be randomly generated by the system making the API request and will form the Basic Authorization token to be used in further requests on behalf of the actor specified in the data field. Ensure you populate the data.actor field with the actor returned from Step 1 – if you specified a unique attribute, this actor's account may be different to the one originally generated.

The username and password are then combined together to create a Basic Auth header as described in on the authentication page.

Authentication tokens are heavily cached so please ensure a unique username is created for every request or you may encounter unexpected issues.

3. Content Launch

With both an actor and auth token created, it's now possible to generate a URL that will launch a specific activity on behalf of a user. The structure of the URL looks like:

https://example.clearlrs.com/api/activities/launch?activityId=ACTIVITY_ID&auth=AUTH_TOKEN

Note the following query parameters:

Param	Description
activityId	The ID of the activity that should be launched
auth	The basic auth token generated in Step 2 in the form Basic TOKEN

An example for the credentials generated in step 2 may look like:

https://example.clearlrs.com/api/activities/launch?activityId=https%3A%2F%2Fexample.hub.clearlrs.com&auth=Basic%20UkFORE9NX0tFWTpSQU5ET01fU0VDUkVU

Loading this URL in a browser will authenticate, launch and redirect to the content for the given activityId.