Installation & activation

Install the WHMCS server module and addon, configure at least one control-plane provider, provision GoTrue infrastructure, sync customer plans, and place a test order before selling.

Time: ~20 min · Requires: WHMCS 9.0+ · Core: 1.61.13+ · License: one per WHMCS install (pricing)

1. Prerequisites

• WHMCS 9.0 or later with the system cron running.
• PHP 8.2 / 8.3 / 8.4 with ionCube Loader 13+ — the module’s PHP is encoded, so ionCube must be present before activation.
• ImpulseCore 1.61.13+ installed and active before activating ImpulseAuth. ImpulseAuth uses it for licensing, the cron runner, lifecycle, the audit log, the shared Email Delivery service, and the Security & Maintenance pipeline.
• An IAUTH- license key. Your WHMCS install’s domain is recorded the first time the key is validated; you don’t enter it anywhere.
• A VPS provider account for your control planes: Vultr, Hetzner Cloud, DigitalOcean, Linode, AWS, Azure, Google Cloud, or Proxmox VE. See Providers & control plane.
• A Cloudflare-hosted zone for the auth domain, with an API token. ImpulseAuth writes the DNS records and issues the wildcard certificate through it.
• Transactional email credentials (smtp2go, Postmark, Mailgun, SendGrid, Resend, Amazon SES, or any SMTP server) so projects can send confirmations, magic links, and password resets.

Verify ionCube first

Run php -m | grep -i ionCube with the PHP binary your WHMCS uses: /opt/plesk/php/8.3/bin/php on Plesk, /opt/cpanel/ea-php83/root/usr/bin/php on cPanel, or /usr/bin/php (whatever which php returns) on a plain Linux server. No output means the loader is missing — enable it under Tools & Settings → PHP Settings on Plesk or in WHM’s PHP extension settings on cPanel, or install the loader from ioncube.com and add its zend_extension line to php.ini.

2. Upload the files

Download the release from your license in the Impulse Software portal and extract impulseauth-<version>.zip into the WHMCS root. You should end up with the server module, the addon, and the hook file:

whmcs/
|-- modules/
|   |-- servers/impulseauth/        (includes health.php)
|   `-- addons/impulseauth_addon/
`-- includes/hooks/impulseauth_hooks.php

The new files need the same owner and group as the rest of your WHMCS files — on Plesk that’s the subscription user, on cPanel the account’s cPanel user, and on a plain Linux server typically www-data. If you extracted them as root, copy the ownership of the existing directories from the WHMCS root:

chown -R --reference=modules/servers modules/servers/impulseauth
chown -R --reference=modules/addons modules/addons/impulseauth_addon
chown --reference=includes/hooks includes/hooks/impulseauth_hooks.php

3. Activate the addon

1. In WHMCS admin, open System Settings → Addon Modules.
2. Activate ImpulseAuth.
3. Set access control for the admin roles that should manage Auth.
4. Open Addons → ImpulseAuth and confirm the Dashboard shows the Get started in 3 steps checklist.

Activation creates the mod_impulseauth_* tables, seeds Free/Dev/Pro plans, installs default email templates, registers the module manifest with ImpulseCore, and syncs the Auth cron task declarations.

If ImpulseCore isn’t ready

WHMCS reports the addon as activated either way, so read the activation message. If ImpulseCore is older than 1.61.13, it says ImpulseCore registration failed and names the version ImpulseAuth needs; if ImpulseCore isn’t installed, it says so. In both cases ImpulseAuth is not registered — no cron tasks, licensing, or lifecycle. Install or update ImpulseCore, then deactivate and reactivate ImpulseAuth.

Upgrades

Upload a new release over the existing directories, then open Addons → ImpulseAuth once so WHMCS runs the module’s upgrade routine: it adds new columns and re-registers the manifest with ImpulseCore. Deactivating and reactivating is also safe — the data tables are kept — and re-runs the full table setup and registration.

4. Enter your license key

1. Open Addons → ImpulseCore → Modules & Licensing → Licenses.
2. Paste your IAUTH- key into the ImpulseAuth row.
3. Click Save.
4. Confirm the license is active before provisioning production control planes; the status also shows under ImpulseAuth → Diagnostics → License.

An ImpulseAuth license covers one WHMCS install; current prices are on the pricing page. Core remains the source of truth for license state, grace windows, and revalidation.

5. Configure providers

Open Settings → General & Access and set the WHMCS server IPv4/IPv6 addresses (written into each control plane’s firewall), the default region code, the provisioning timeout, the default GoTrue version, and an optional JWT secret pepper. The Break-Glass Access panel on the same page holds the SSH settings; they are used only while the HIGH RISK break-glass toggle is on, and it is off by default.

Then open Settings → Providers & Regions. Vultr, Hetzner Cloud, DigitalOcean, and Linode take an API token, default region, default plan, and default OS image. AWS, Azure, and Google Cloud take their own credentials (an IAM access key, a service principal, or a service-account key). Proxmox VE uses API URL, token, optional certificate fingerprint, snippet storage, default node, and a JSON plan catalog backed by cloud-init template VMs.

Same provider shape as the rest of the family

Auth, Objects, and Postgres all use the shared ImpulseCore provider catalog, including Proxmox VE. For Proxmox, server identity is stored as node:vmid.

6. Set DNS, TLS, and email

1. Open Settings → DNS & TLS.
2. Set the auth domain, for example auth.example.com.
3. Save a Cloudflare token with Zone → Zone → Read and Zone → DNS → Edit permission (and the zone ID if the auth domain sits inside a parent zone), then click Test DNS Connection.
4. Set the Let’s Encrypt registration email and DNS-01 propagation delay.
5. Open Settings → Email Delivery and save the transactional email credentials.

Each control plane requests a wildcard certificate for customer project hostnames and uses the email provider for account confirmation, magic link, password reset, and account-change messages.

7. Create plans and sync WHMCS products

Plans define the commercial Auth product: tier, MAU limit, project count, OAuth provider count, custom-domain count, MFA, BYO SMTP, anonymous sessions, leaked-password detection, audit logs, price, and WHMCS product mapping. The tier (Free, Dev, or Pro) decides which other features, such as SSO and SCIM, a plan includes.

Seeded plan	Default role	Notes
Free	Starter	Core GoTrue project management with low limits.
Dev	Staging	MFA, all OAuth providers, roles, hooks, and phone sign-in, with mid-size limits.
Pro	Commercial	Full feature set, SSO/SCIM, BYO SMTP, a custom domain, and larger limits.

1. Open Plans & Products.
2. Review limits, feature gates, and prices.
3. Click Create WHMCS product (or Re-sync WHMCS product) on a plan, or Sync all active plans to WHMCS.
4. Open the generated WHMCS product and verify module settings, visibility, pricing, and welcome email.

8. Provision a control plane

1. Open Infrastructure → + Provision New Server.
2. Choose provider, region, VPS plan, and capacity. For Proxmox, region means node and the plan maps to a cloud-init template VM.
3. Submit the form; the row starts as provisioning.
4. ImpulseAuth writes the control plane’s DNS records in Cloudflare once the host answers.
5. Wait for the row to flip to active — the refresh_servers cron checks every 2 minutes, or use Refresh health from the row’s menu.

The bootstrap installs Nginx, PostgreSQL, certbot, the GoTrue systemd template, and the FastAPI Admin Proxy. Health checks use the Admin Proxy over HTTPS.

Apply/Rebuild is in-place

Apply/Rebuild on a server row keeps the VPS, IP, Postgres schemas, Nginx project map, and stored credentials and re-applies the current bootstrap through the server’s scoped Admin Proxy. It falls back to SSH only while the HIGH RISK break-glass toggle is on.

9. Security, SSO, and reports

ImpulseAuth registers security collectors with ImpulseCore so GoTrue/Auth CVEs, OS updates, patch windows, snapshots, and stale collector states show in the same Security & Maintenance pipeline as the other modules.

• Enterprise SSO supports SAML and OIDC providers with metadata health checks and enforcement modes.
• SCIM provisioning, role mapping, OAuth app risk signals, auth hooks, and password/session policy contribute to customer reports.
• JWT signing-key rotation is append-only; every rotation writes history instead of overwriting in place.
• Mark a project protected (Customers → the project → Mark protected) when your own business depends on it — for example, the project behind your own sign-in. ImpulseAuth then refuses to suspend it from the Customers page, WHMCS can’t terminate it, and the day-7 purge skips it.

10. Troubleshooting

• Addon activates but tabs stay gated. Verify the IAUTH- key in ImpulseCore and confirm Core can reach the licensing endpoint.
• Provider test fails. Re-check the provider token, default region/plan, and provider-side account limits.
• Control plane stays provisioning. Inspect provider create status, the bootstrap log (View Log in the row’s menu), and Admin Proxy health from the server row.
• Proxmox provision has no IP. Confirm the template has qemu-guest-agent installed/enabled and working guest networking.
• Project order does not create an endpoint. Confirm the WHMCS product is synced to an active Auth plan and at least one control plane is active in the selected region.