Everyone

Testing a Server Connection

How to verify that Commerce can reach a server and authenticate with its provisioning module before orders are placed.

Last updated 1776211200

Overview

Commerce provides two ways to test a server connection. Both ultimately call the module's testConnection() method, which sends a lightweight authenticated request to the Panel API and checks for a valid response.

Always test after adding a server or rotating credentials.

Method 1 — Test on the Server Form

Available on both Add Server and Edit Server pages.

  1. Fill in all credential fields.
  2. Click Test Connection.
  3. An inline result appears immediately — no page reload.

Success: Green banner with server info (e.g. server name, version from the stats endpoint). Failure: Red banner with the error returned by the module.

Fix any errors before clicking Save. Saving a server with bad credentials does not block you, but all provisioning jobs will fail until the credentials are corrected.

Method 2 — Test from the Servers List

  1. Go to Admin → Infrastructure → Servers.
  2. Click the test icon (plug icon) in the row for the server you want to test.
  3. A status badge updates inline: Online or Offline.

This is the fastest way to check all servers at a glance. Run a sweep after network changes or firewall updates.

What testConnection() Does for Opterius Panel

The OpteriusPanelModule::testConnection() method:

  1. Generates a current Unix timestamp.
  2. Computes X-Signature = HMAC-SHA256(timestamp + "", api_token) (empty body for GET).
  3. Sends GET /api/server/stats with X-Timestamp and X-Signature headers.
  4. Expects HTTP 200 with a valid JSON stats payload.
  5. Returns ProvisioningResult::success() with the stats data, or ProvisioningResult::failure() with the error.

For other module types, testConnection() performs an equivalent lightweight auth check specific to that API.

Common Failures

Error Cause Fix
401 Unauthorized api_token is wrong or expired Generate a new token in Panel → Settings → API
Connection refused (cURL 7) Wrong port in api_url, or Panel server firewall blocking Commerce IP Check the api_url port; open the port on the Panel server firewall
Could not resolve host Typo in the hostname, or DNS not resolving Check the hostname in api_url
SSL certificate verify failed Panel using a self-signed certificate Install a valid certificate on Panel, or add SSL_VERIFY=false to Commerce .env
504 Gateway Timeout Panel is overloaded or Nginx/Apache not running Check Panel server health
403 Forbidden Commerce IP not in Panel's allowlist (if Panel has IP restriction) Add Commerce server IP to Panel allowlist

After Changing Credentials

If you rotate an api_token in Panel settings:

  1. Go to Admin → Infrastructure → Servers → edit the server.
  2. Paste the new token into the api_token field.
  3. Click Test Connection — confirm success.
  4. Save.

If you save without testing and the new token is wrong, all in-flight provisioning jobs will fail. Check the Provisioning Log immediately if services stop provisioning.

Related

Previous
← Capacity Tracking & Auto-Assign
Next
Opterius Panel Module →