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

{% hint style="info" %}
The following guide requires a third-party **Service Account** for authentication of all API requests. Please contact our support team for assistance.
{% endhint %}

### 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**](https://dev.clearxp.com/clear-api-reference/actors#insert-update-agent)

```bash
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.

{% hint style="info" %}
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.
{% endhint %}

### 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.&#x20;

[**POST /api/auth/basic**](https://dev.clearxp.com/getting-started/authentication#basic-authentication)

```bash
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**](https://en.wikipedia.org/wiki/Basic_access_authentication) 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**](https://dev.clearxp.com/clear-api-reference/authentication) page.

{% hint style="warning" %}
Authentication tokens are heavily cached so please ensure a unique **username** is created for every request or you may encounter unexpected issues.
{% endhint %}

### 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**.