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.
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.
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",
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.
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.
curl -X POST "https://example.clearlrs.com/api/auth/basic" -H "authorization: API_TOKEN" -H "content-type: application/json" -i --data-binary @- << EOF
passwordvalues 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
datafield. Ensure you populate the
data.actorfield 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.
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:
Note the following query parameters:
An example for the credentials generated in step 2 may look like:
Loading this URL in a browser will authenticate, launch and redirect to the content for the given activityId.