# 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**](/getting-started/authentication.md#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**](/clear-api-reference/authentication.md) 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**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.clearxp.com/guides/account-provisioning-and-launch.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.