LiquidFiles Documentation
LiquidFiles Documentation
On This Page

Certificate API

The Certificate API enables you to manage SSL/TLS certificates on your LiquidFiles system programmatically. This is useful for automating certificate deployment from external certificate authorities, ACME clients, or internal PKI systems.

Authentication

The Certificate API requires a Sysadmin API key. Regular admin or user API keys will receive a 403 Forbidden response. For basic authentication information, please see the API authentication documentation.

Certificate Attributes

The following attributes are returned when accessing a certificate:

Response Attributes
Parameter Type Description
domain String The public hostname of the domain this certificate is for.
subject String The certificate subject (Common Name).
issuer String The certificate issuer (Common Name).
valid_from String The start of the certificate validity period.
valid_to String The end of the certificate validity period.
key_length String The key length, e.g. "2048 bit".
self_signed Boolean True if the certificate is self-signed.
certificate_type String Either "traditional" or "letsencrypt".
certificate_pem String The PEM-encoded certificate (including any intermediate chain certificates).

View Certificate

Returns the current certificate metadata and PEM-encoded certificate for the domain.

Request Info
Info Value
Request URL /system/certificate
Request VERB GET

Example using curl:

curl -X GET -H "Authorization: Bearer "$SYSADMIN_API_KEY:x" \
     -H "Accept: application/json" \
     https://liquidfiles.company.com/system/certificate

{"certificate":
  {
    "domain": "liquidfiles.company.com",
    "subject": "liquidfiles.company.com",
    "issuer": "R11",
    "valid_from": "Mar 15 00:00:00 2026 GMT",
    "valid_to": "Jun 13 00:00:00 2026 GMT",
    "key_length": "2048 bit",
    "self_signed": false,
    "certificate_type": "letsencrypt",
    "certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIF...base64...\n-----END CERTIFICATE-----\n"
  }
}

Upload Certificate

Upload a new PEM-encoded certificate and private key. On success, the certificate is installed and nginx and postfix are automatically reloaded. The certificate type is set to "traditional".

Request Info
Info Value
Request URL /system/certificate
Request VERB POST
Request Parameters
Parameter Type Required Description
certificate_pem String Yes The PEM-encoded certificate. Include any intermediate chain certificates by concatenating them after the leaf certificate.
certificate_key String Yes The PEM-encoded private key. Must not be encrypted (no passphrase).

The server validates that the certificate and key are valid PEM format and that the key matches the certificate (modulus check). On validation failure, a 422 Unprocessable Entity response is returned with an error message.

Example using curl:

curl -X POST -H "Authorization: Bearer $SYSADMIN_API_KEY:x" \
     -H "Accept: application/json" \
     --data-urlencode "certificate_pem=$(cat /path/to/cert.pem)" \
     --data-urlencode "certificate_key=$(cat /path/to/key.pem)" \
     https://liquidfiles.company.com/system/certificate

Successful response (HTTP 200 OK):

{"certificate":
  {
    "domain": "liquidfiles.company.com",
    "subject": "liquidfiles.company.com",
    "issuer": "R11",
    "valid_from": "Mar 15 00:00:00 2026 GMT",
    "valid_to": "Jun 13 00:00:00 2026 GMT",
    "key_length": "2048 bit",
    "self_signed": false,
    "certificate_type": "traditional"
  }
}

Error response (HTTP 422 Unprocessable Entity):

[{"error": "Certificate doesn't match key"}]

Multi-Domain Installations

For LiquidFiles installations with multiple domains, the API operates on the domain matching the hostname used in the API request. To manage certificates for different domains, make the API call to each domain's hostname separately.

For example, if your system has two domains files.company.com and secure.company.com, upload certificates by making API calls to each hostname:

# Upload certificate for files.company.com
curl -X POST -H "Authorization: Bearer $SYSADMIN_API_KEY:x" \
     -H "Accept: application/json" \
     --data-urlencode "certificate_pem=$(cat files-cert.pem)" \
     --data-urlencode "certificate_key=$(cat files-key.pem)" \
     https://files.company.com/system/certificate

# Upload certificate for secure.company.com
curl -X POST -H "Authorization: Bearer $SYSADMIN_API_KEY:x" \
     -H "Accept: application/json" \
     --data-urlencode certificate_pem=$(cat secure-cert.pem)" \
     --data-urlencode certificate_key=$(cat secure-key.pem)" \
     https://secure.company.com/system/certificate