Plugin JSON API

Since 0.15.0, FleetSSL cPanel provides a versioned HTTP JSON API that may be used by non-privileged (non-root) cPanel users.

This API can be issued to list, issue, remove, map and unmap SSL certificates managed by the FleetSSL cPanel plugin.

Calling the HTTP JSON API

The API is accessed by the following URI schema:

https://{HOSTNAME}:2083/frontend/paper_lantern/letsencrypt/letsencrypt.live.cgi?api_version={API_VERSION}&api_function={API_FUNCTION}

Mandatory Headers

All API requests MUST carry the Accept: application/json header.

All API requests that come with a request body (i.e. POST requests) MUST carry the Content-Type: application/json header.

Authentication

To authenticate to this API, you should follow the regular cPanel API Authentication practices. In practice, this will usually mean one of:

API Endpoints

API Version

There is only a single API version at present: 1. This should be passed as the api_version query parameter in the URL.

API Functions

This should be passed as the api_function query parameter in the URL.

API Function Description HTTP Method
list-certificates Provides a list of virtual hosts that have Let’s Encrypt certificates configured in the user’s account, along with certificate details. GET
issue-certificate Issues and installs a Let’s Encrypt certificate to the specified virtual host, with the specified DNS identifiers on the certificate. POST
remove-certificate Unconfigures and uninstalls the installed Let’s Encrypt SSL certificate from the specified virtual host. POST
reinstall-certificate Without re-issuing the certificate, reinstalls the respective Let’s Encrypt SSL certificate to the specified virtual host. POST
reuse-certificate Shares a certificate from a specified source virtual host to a specified target virtual host. See Wildcards for more info. POST
remove-certificate-reuse Unshares a certificate from a specified target virtual host. POST

Keep reading to see example requests and responses for each of these endpoints.

list-certificates

Provides a list of virtual hosts that have Let’s Encrypt certificates configured in the user’s account, along with certificate details.

Request Schema

This endpoint does not accept a request body.

Response Schema

{
  "success": true,
  "errors": null,
  "data": {
    "virtual_hosts": {
      "example.org": {
        "virtual_host": "example.org",
        "dns_identifiers": [
          "*.example.org",
          "example.org"
        ],
        "challenge_method": "dns-01",
        "cpanel_cert_id": "example_org_c17ac_e7973_1562912741_feadfa305d9ae4762638c89ce157c068",
        "cpanel_key_id": "c17ac_e7973_e2b23c1a4c9b7d3355e1a7a1acc8ceba",
        "cert_pem": "-----BEGIN CERTIFICATE-----...",
        "issuer_pem": "-----BEGIN CERTIFICATE-----...",
        "privkey_pem": "-----BEGIN RSA PRIVATE KEY-----...",
        "order_url": "https://acme-v02.api.letsencrypt.org/acme/order/000/001"
      }
    }
  }
}

Example

# cURL Example
curl -u "username:password" -H 'Accept: application/json' \
"https://HOSTNAME:2083/frontend/paper_lantern/letsencrypt/letsencrypt.live.cgi?api_version=1&api_function=list-certificates"
# PHP Library Example (https://packagist.org/packages/fleetssl/fleetssl-cpanel-api-client)
<?php
require_once 'vendor/autoload.php';
$cl = new \FleetSSL\Cpanel\APIClient("cpanel.example.org", "user", "password");
$resp = $cl->listCertificates();
// $resp->success === true;
// $resp->data->virtual_hosts = [...];
?>

issue-certificate

Issues and installs a Let’s Encrypt certificate to the specified virtual host, with the specified DNS identifiers on the certificate.

Request Schema

{
  "virtual_host": "example.org",
  "dns_identifiers": [
    "example.org",
    "www.example.org",
    "cpanel.example.org"
  ],
  "challenge_method": "http-01",
  "dry_run": false
}
Parameter Description Values
virtual_host The cPanel virtual host (primary, addon or subdomain) to which this certificate should be installed example.org
dns_identifiers The full list of DNS identifiers that should be present on the final certificate, including the virtual host. ["example.org", "*.example.org"]
challenge_method Either http-01 or dns-01. You MUST use dns-01 if any of your DNS identifiers are wildcards. "http-01"
dry_run A dry run will use the Let’s Encrypt staging server to issue a test certificate, and will then discard it without installing it. It is useful to test whether a certificate issuance would succeed, without wasting your rate limit. false

Response Schema

Success

{
  "success": true,
  "errors": null,
  "data": "The SSL certificate is now installed onto the domain example.org’” using the IP address “127.0.0.1”. Apache is restarting in the background.\n"
}

Failure

{
  "success": false,
  "errors": [
    "Failed to isssue certificate",
    "Updating challenge for test.example.org: acme: error code 400 \"urn:ietf:params:acme:error:connection\": dns :: DNS problem: NXDOMAIN looking up A for test.example.org (order URL: https://acme-staging-v02.api.letsencrypt.org/acme/order/000/001)"
  ],
  "data": null
}

Example

# cURL Example
curl -u 'username:password' -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' \
"https://HOSTNAME:2083/frontend/paper_lantern/letsencrypt/letsencrypt.live.cgi?api_version=1&api_function=issue-certificate" \
--data '{"virtual_host":"example.org", "dns_identifiers": ["www.example.org", "example.org", "cpanel.example.org"], "challenge_method": "http-01", "dry_run": false}' 
# PHP Library Example (https://packagist.org/packages/fleetssl/fleetssl-cpanel-api-client)
<?php
require_once 'vendor/autoload.php';
$cl = new \FleetSSL\Cpanel\APIClient("cpanel.example.org", "user", "password");
$resp = $cl->issueCertificate("example.org", ["www.example.org", "example.org", "cpanel.example.org"], 
                              $challengeMethod = "http-01", $dryRun = false);
// $resp->success === true;
?>

remove-certificate

Unconfigures and uninstalls the installed Let’s Encrypt SSL certificate from the specified virtual host.

Request Schema

{
  "virtual_host": "example.org"
}
Parameter Description Values
virtual_host The cPanel virtual host (primary, addon or subdomain) from which a configured certificate should be removed example.org

Response Schema

{
  "success": true,
  "errors": null,
  "data": null
}

Example

# cURL Example
curl -u 'username:password' -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' \
"https://HOSTNAME:2083/frontend/paper_lantern/letsencrypt/letsencrypt.live.cgi?api_version=1&api_function=remove-certificate" \
--data '{"virtual_host":"example.org"}'
# PHP Library Example (https://packagist.org/packages/fleetssl/fleetssl-cpanel-api-client)
<?php
require_once 'vendor/autoload.php';
$cl = new \FleetSSL\Cpanel\APIClient("cpanel.example.org", "user", "password");
$resp = $cl->removeCertificate("example.org");
// $resp->success === true;
?>

reinstall-certificate

Without re-issuing the certificate, reinstalls the respective Let’s Encrypt SSL certificate to the specified virtual host.

Request Schema

{
  "virtual_host": "example.org"
}
Parameter Description Values
virtual_host The cPanel virtual host (primary, addon or subdomain) on which the configured certificate should be re-installed example.org

Response Schema

{
  "success": true,
  "errors": null,
  "data": "The certificate was successfully installed on the domain example.org”."
}

Example

# cURL Example
curl -u 'username:password' -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' \
"https://HOSTNAME:2083/frontend/paper_lantern/letsencrypt/letsencrypt.live.cgi?api_version=1&api_function=reinstall-certificate" \
 --data '{"virtual_host":"example.org"}'
# PHP Library Example (https://packagist.org/packages/fleetssl/fleetssl-cpanel-api-client)
<?php
require_once 'vendor/autoload.php';
$cl = new \FleetSSL\Cpanel\APIClient("cpanel.example.org", "user", "password");
$resp = $cl->reinstallCertificate("example.org");
// $resp->success === true;
?>

reuse-certificate

Shares a certificate from a specified source virtual host to a specified target virtual host. See Wildcards for more info.

Request Schema

{
  "dest_virtual_host": "subdomain.example.org",
  "src_virtual_host": "example.org"
}
Parameter Description Values
src_virtual_host The cPanel virtual host (primary, addon or subdomain) from which a configured certificate should be copied example.org
dest_virtual_host The cPanel virtual host (primary, addon or subdomain) where the certificate should be installed subdomain.example.org

Keep in mind, doing this only makes sense when the certificate from the source virtual host, covers at least one of the domains in the destination virtual host. In the above example, the source certificate might cover *.example.org, so it is valid for the destination virtual host (subdomain.example.org). Attempting to share a certificate to a destination virtual host that does not share any names in common with the source virtual host’s certificate, will result in an error.

Response Schema

{
  "success": true,
  "errors": null,
  "data": null
}

Example

# cURL Example
curl -u 'username:password' -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' \
"https://HOSTNAME:2083/frontend/paper_lantern/letsencrypt/letsencrypt.live.cgi?api_version=1&api_function=reuse-certificate" \
--data '{"dest_virtual_host":"subdomain.example.org","src_virtual_host":"example.org"}' 
# PHP Library Example (https://packagist.org/packages/fleetssl/fleetssl-cpanel-api-client)
<?php
require_once 'vendor/autoload.php';
$cl = new \FleetSSL\Cpanel\APIClient("cpanel.example.org", "user", "password");
$resp = $cl->reuseCertificate("example.org", "subdomain.example.org");
// $resp->success === true;
?>

remove-certificate-reuse

Unshares a certificate from a specified target virtual host.

Request Schema

{
  "dest_virtual_host": "subdomain.example.org",
}
Parameter Description Values
dest_virtual_host The cPanel virtual host (primary, addon or subdomain) from which the configured shared certificate should be unshared example.org

Response Schema

{
  "success": true,
  "errors": null,
  "data": null
}

Example

# cURL Example
curl -u 'username:password' -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' \
"https://HOS1TNAME:2083/frontend/paper_lantern/letsencrypt/letsencrypt.live.cgi?api_version=1&api_function=remove-certificate-reuse" \
--data '{"dest_virtual_host":"subdomain.example.org"}' 
# PHP Library Example (https://packagist.org/packages/fleetssl/fleetssl-cpanel-api-client)
<?php
require_once 'vendor/autoload.php';
$cl = new \FleetSSL\Cpanel\APIClient("cpanel.example.org", "user", "password");
$resp = $cl->removeCertificateReuse("subdomain.example.org");
// $resp->success === true;
?>

PHP API Client

We have provided a basic PHP API client library for those that do not want to write the HTTP requests themselves.

You can download it with Composer:

composer require fleetssl/fleetssl-cpanel-api-client

and then use it (see above for more usage examples):

<?php
require_once 'vendor/autoload.php';
$cl = new \FleetSSL\Cpanel\APIClient("cpanel.example.org", "user", "password");
$resp = $cl->issueCertificate("example.org", ["example.org", "*.example.org*"], "dns-01", true);
// $resp->success === true;
?>