Provider guides
Plesk: configuration and operations
Create Plesk customers and hosting subscriptions through the Plesk XML API, with suspension, termination, verified plan changes and status sync.
On this page
Status and workflow
The Plesk extension creates a Plesk customer and a hosting subscription per Agovena service through the Plesk Obsidian XML API. It supports plan validation, create with idempotent retry and reconciliation, status synchronization, suspension, unsuspension, termination with customer cleanup, verified plan changes to an existing service plan and a read-only customer panel with status, Plesk username, plan and domain.
Production-ready for the documented scope. Every operation under Supported operations is implemented against the Plesk Obsidian XML API documentation and verified with automated tests that replace the provider with faked HTTP responses, without network calls. Live acceptance on your own Plesk account remains an operator responsibility: create, suspend, unsuspend, change and terminate one disposable subscription on your own Plesk server before you sell it. Operations under Not supported are not advertised.
Requirements
- Agovena Core
^0.0.1. - The Provisioning Module, enabled before this extension.
- A Plesk Obsidian server reachable over HTTPS and an administrator secret key.
- The IP address that new subscriptions are hosted on, and existing administrator service plans.
Set up the package
- Enable the Provisioning Module, then install and enable Plesk in Admin > Extensions.
- Save
api_urlasscheme://host:portonly, for examplehttps://server.example.com:8443. - Save the administrator secret key in
api_tokenand the hosting IP inip_address. The key is encrypted at rest. - Keep
verify_tlsenabled. - Run Test connection. It sends the read-only
serverget_protospacket. - On each provisionable product, set Service plan to the exact name of an existing administrator service plan and Domain to the subscription domain.
Supported operations
Every call is POST https://host:port/enterprise/control/agent.php with an XML packet and the secret key in the KEY header.
| Operation | Packet |
|---|---|
| Health check | server/get_protos |
| List plans on create and plan change | service-plan/get |
| Create customer | customer/add |
| Create subscription | webspace/add with the plan name and hosting IP |
| Reconcile customer | customer/get by login |
| Reconcile subscription, status sync, plan check | webspace/get by name or ID |
| Suspend, unsuspend | webspace/set with status 16 or 0 |
| Terminate subscription | webspace/del |
| Customer cleanup check | webspace/get by owner-id |
| Delete customer | customer/del |
| Change plan | webspace/switch-subscription with the plan GUID |
Status sync maps 0 to active and 16, 32, 64 and 256 to suspended after checking the owner-id. A plan change is recorded only after the subscription lists the new plan GUID.
Not supported
- Customer power actions, single sign-on and password handover.
- Reseller-owned plans and add-on plans.
- Checkout capacity checks and moving a subscription between servers.
- Adopting existing Plesk customers or subscriptions.
Failure handling and ownership
- Plesk answers HTTP 200 even on failure, so every
result/statusmust beok. A packet-levelsystemerror fails the call (1001means refused credentials). Only error code1013, object does not exist, is read as absent. Any other shape, a non-200 status or a redirect fails closed. - Responses are parsed without network access. Document type declarations and entities are refused.
- Ownership is proven only by a row in
plesk_accounts, inserted before Agovena's own create calls. Endpoint plus subscription, domain and customer login are unique. Customers and subscriptions are never adopted fromprovider_mapping,external_ref, product settings or a lookup. - Every lifecycle call requires the claim endpoint to match the current connection, and state changes are a compare-and-swap on
revision. - The customer login is
agv, eight random lowercase characters and the base36 service ID. It is stored beforecustomer/addand is also the FTP login. A rejectedcustomer/addreplaces the stored login, because the old one may belong to someone else. - A timeout, HTTP error or malformed response marks the claim
unknown. The retry reads the stored login and domain; code1013means absent and the object is created, and a subscription is accepted only when itsowner-idis the customer Agovena created. Anything else goes to manual review. - Terminate deletes only the claimed subscription, then deletes the customer Agovena created only when it has no other subscription. A failed cleanup keeps the customer ID so a retry resumes it. A missing subscription is never reported as terminated.
- Customer and FTP passwords are generated per request, sent once and never stored, logged or returned. The customer sets a new password through the Plesk password reset.
Configuration contract
| Field | Type | Required | Secret | Default |
|---|---|---|---|---|
api_url |
string |
Yes | No | Empty |
api_token |
string |
Yes | Yes | Empty |
ip_address |
string |
Yes | No | Empty |
verify_tls |
boolean |
No | No | true |
timeout |
string |
No | No | "20" |
api_token holds the Plesk administrator secret key and ip_address the hosting IP for new subscriptions. Calls never follow redirects, verify TLS, pin DNS through the shared provisioning HTTP client and are refused in the demo environment. Production refuses plain HTTP and unverified TLS. Store secret values only in the protected extension settings, never in product descriptions, URLs, screenshots or shared examples.