Skip to content
agovena.
agovena.
Get started
Community

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

  1. Enable the Provisioning Module, then install and enable Plesk in Admin > Extensions.
  2. Save api_url as scheme://host:port only, for example https://server.example.com:8443.
  3. Save the administrator secret key in api_token and the hosting IP in ip_address. The key is encrypted at rest.
  4. Keep verify_tls enabled.
  5. Run Test connection. It sends the read-only server get_protos packet.
  6. 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/status must be ok. A packet-level system error fails the call (1001 means refused credentials). Only error code 1013, 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 from provider_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 before customer/add and is also the FTP login. A rejected customer/add replaces 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; code 1013 means absent and the object is created, and a subscription is accepted only when its owner-id is 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.

View the package entry

Sources

Search documentation

Search guides, commands and API endpoints

What are you looking for?

Documentation