---
title: "Configure"
description: "Configure the WHMCS module in three steps: obtain your Panel API key, add your panel to the addon, and create a product that provisions IPTV lines or sub-reseller accounts through the panel."
---

Configuring the module is three ordered steps. Get an API key from your Xtream AI Panel. Register your panel in the WHMCS addon so the module knows where to talk. Create a WHMCS product that uses the `xtreamai` server module, and tie it to a package and a set of bouquets on that panel. Each step takes about a minute if you already have the values on hand.

This page assumes the module is already installed and activated. If it is not, jump back to [Install](/docs/?page=whmcs-module-install) first.

## Step 1. Obtain a Panel API key

The API key is how the module proves to your panel that it is entitled to create lines, adjust credits and read the catalog. The panel decides what each key is allowed to do based on the scopes you tick at issuance time. The module needs a small, specific set of scopes; picking them correctly here saves you from `403 insufficient_scope` errors later on.

### If you are a panel administrator

Log in to your Xtream AI Panel with your admin account. Open **Settings → Panel API Keys**. Click **Create key**, fill in a **label** (`WHMCS-production-2026` is a reasonable convention), and tick the scopes.

### If you are a reseller

Log in to your reseller area on the panel. Open **Settings → Panel API Keys**. If you do not see the tab, your admin has not yet enabled the `can_create_api_keys` permission on your member group. Ask them to tick **Reseller settings → Member groups → Can create API keys** for your group. Once the tab appears, click **New key**.

### Which scopes to tick

The recommended scope sets depend on which kind of product you will provision.

For **Line products only** (both reseller and admin keys):

- `lines:read`
- `lines:write`
- `packages:read`
- `bouquets:read`

Add `streams:read` and `vods:read` if you plan to use the **Catalog** tab in the addon to browse the panel's live channels and VOD entries. They are read-only and cost nothing to include.

For **Sub-Reseller products** (admin key only), add on top of the Line scopes:

- `resellers:read`
- `resellers:write`
- `subresellers:write`

> [!IMPORTANT]
> The `resellers:read` and `resellers:write` scopes are admin-only. The panel refuses to attach them to a reseller key at issuance. If you plan to sell Sub-Reseller products, the key you paste into the module must come from a panel admin account. See [Reseller vs Admin Keys](/docs/?page=whmcs-module-key-types) for the full matrix.

Leave the optional fields (IP allow-list, rate limit, expiration) empty for now. You can tighten them later without regenerating the key.

Click **Save**. The panel shows the full token on the screen, in the form:

```
pk_live_<12-char prefix>.<43-char secret>
```

Copy it immediately. Only the prefix is retrievable later; the secret half is displayed once and never again.

> [!WARNING]
> If you close the dialog without copying the token, the key is not lost, but the secret is. You will have to rotate the key from the same page to get a new secret. Full contract in [Panel API Authentication](/docs/?page=panel-api-authentication).

## Step 2. Add your panel to the addon

Now open WHMCS. Go to **Addons → Xtream AI Panel → Panels**, and click **Add Panel**. The form has one column of fields; fill them in as follows.

### Field reference

| Field | Purpose |
|---|---|
| **Panel name** | Free-text label for your own bookkeeping. Shown in the panel picker on WHMCS products and in the module logs. `My main panel` is a fine starting value. |
| **API URL** | The base URL of your Xtream AI Panel, including the scheme and no trailing slash. For example, `https://panel.example.com`. Do not add `/panel-api/v1` here; the module appends the path segments itself. |
| **M3U URL** | Optional. The base URL your customer plugs into their IPTV app to fetch the M3U playlist. Shown on the client-area card if set, hidden if left empty. |
| **API access key** | The full `pk_live_...` token you copied in Step 1. Stored encrypted at rest with WHMCS's own `encrypt()` helper; never rendered, never logged. |
| **Key type** | Either **Reseller** or **Admin**. This must match what the token actually is. A reseller token attached as Admin, or an admin token attached as Reseller, will surface confusing errors later. |
| **Admin owner member_id** | Only shown when Key type is Admin. Numeric member id (the `id` column of the reseller record on the panel) that will own every line this panel entry creates. Required for admin keys. If you are a panel administrator whose token belongs to a reseller record on the panel, use that reseller's id here. |
| **Verify SSL** | On by default. Leave it on for production. Only disable it if your panel serves an internal or self-signed certificate you know is valid. Disabling shows a persistent warning banner in the admin UI. |
| **Active** | On by default. Only inactive panels are hidden from the WHMCS product picker. Turn it off for retired panels you want to keep on file. |

### Verify the connection

Press **Test Connection** before you save. The module calls `GET /panel-api/v1/me` on the panel with the token you pasted, without going through the encrypted-at-rest storage yet, so the test works on unsaved credentials.

A successful test looks like this:

```
Connected (Group: RESELLER, Credits: 42.50)
```

That message means the token is valid, the panel accepted it, and the module resolved the identity behind the key. The Group value and the Credits value come straight from the panel and are only shown when they exist.

If the test fails, the message printed under the button is deliberate. Common ones:

- `Panel authentication failed.` The token was mis-copied. Paste it again.
- `Could not reach the panel.` DNS is wrong, the panel is offline, or your WHMCS host cannot reach the panel over HTTPS.
- `The panel is temporarily unavailable.` The panel returned 503; try again shortly.
- Any TLS-related error. Your panel's certificate is misconfigured, or Verify SSL is on and it should not be. Check the certificate before disabling verification.

Every failure is safe to retry. The connection test is a pure `/me` read and has no side effects on the panel.

When the test reads **Connected**, click **Save** on the form. The panel entry is now stored and encrypted, and it will show up in the panel picker of every WHMCS product that uses the module.

## Step 3. Create a product that provisions through the module

The last step ties a WHMCS product to your panel. In WHMCS admin, go to **Products/Services → Create a new product**.

Under **Details**, pick a product type of **Hosting Account** (the naming is historical; WHMCS uses it for any kind of provisioned service, not just web hosting). Give the product a name your customers will recognize, and pick a group. Save the basic details.

Now open the product's **Module Settings** tab. In the **Module Name** dropdown, choose **xtreamai**. WHMCS reloads the tab and the module's config options appear.

### Module config options

| Option | Purpose |
|---|---|
| **Panel** | Dropdown of every active panel you added in Step 2. Pick the one this product provisions against. |
| **Package Type** | **Official** or **Trial**. Purely a filter on the next dropdown; it changes which packages the module lists but has no effect on what gets stored. |
| **Package** | Dropdown of every package the selected panel exposes, filtered by Package Type. Each entry shows the package name and duration. This choice is what the module sends as `package_id` on `POST /lines` at CreateAccount time, and again at Renew. |
| **Bouquets** | Multi-select picker of every bouquet the panel makes available to the caller. The picker is searchable; on a large catalog this saves scrolling. The selected bouquets are what every new line for this product will carry. |
| **Account Type** | **Line** (default) or **Sub-Reseller**. Line creates an IPTV line on `POST /lines`. Sub-Reseller creates a reseller account on `POST /resellers`. |
| **Credits** | Only shown when Account Type is Sub-Reseller. The initial credit balance the panel assigns on creation. The same value is added again on every renewal. |
| **Max Connections** | Optional per-line concurrent-connection cap. Leave at `0` to inherit the package default. Values from 1 to 100 override the package. This field only takes effect when the panel entry's Key type is Admin; reseller keys silently ignore it. |
| **Sub-Reseller Member Group** | Only shown when Account Type is Sub-Reseller. Numeric id of the panel member group new sub-reseller accounts land in. Required for admin keys; reseller keys inherit the group from their sub-reseller setup on the panel. |

Save the product. The next order for this product will fire the CreateAccount hook, which the module maps onto the exact panel calls described in [Provisioning Modes](/docs/?page=whmcs-module-provisioning-modes).

### A small note on billing cycles

Renewals sync WHMCS's `nextduedate` to the panel's `exp_date`. If the WHMCS billing cycle and the panel package duration disagree, the two systems drift on each renewal in the direction of the panel value. A 30-day package on a monthly WHMCS cycle drifts a day or two per renewal, which is fine. A 1-year panel package attached to a monthly WHMCS cycle jumps a year ahead every time, which is almost certainly a misconfiguration.

Keep the WHMCS billing cycle aligned with the panel package duration and the two systems agree in perpetuity.

## What Sub-Reseller products need in addition

Sub-Reseller products are optional and only work with an admin key. If you plan to sell them, the checklist adds three items on top of the general one above:

1. The panel key must be an admin key with the `resellers:read`, `resellers:write` and `subresellers:write` scopes.
2. The panel entry must have Key type set to **Admin** and a valid **Admin owner member_id** filled in.
3. Every Sub-Reseller product must have a valid **Sub-Reseller Member Group** id set. The id must match a real member group on the panel; otherwise the CreateAccount hook will fail with `The panel rejected the request values.`

The [Provisioning Modes](/docs/?page=whmcs-module-provisioning-modes) page walks through the exact panel calls for Sub-Reseller lifecycle, including the known limitation on Suspend, Unsuspend and Terminate.

## Where to go next

The module is configured. The next thing to read depends on what you want to learn.

- **[Reseller vs Admin Keys](/docs/?page=whmcs-module-key-types).** The complete capability matrix, feature by feature. Useful before you commit to a key type.
- **[Provisioning Modes](/docs/?page=whmcs-module-provisioning-modes).** How Line and Sub-Reseller each map to panel API calls.
- **[Troubleshooting](/docs/?page=whmcs-module-troubleshooting).** The failures that come up most often and how to resolve them.