Hostnames and certificates

A zone serves on its default hostname and on any you add. Five calls manage the hostnames and three more the certificate on one of them; the hostname object says whether SSL is on, whether HTTP is redirected, and which certificate is in place.

The hostname object#

List hostnames#

Every hostname on the zone as DATA.CDN_HOSTNAMES, oldest first, with MESSAGE Data returned for all CDN Hostnames for this CDN Zone.

{
  "CODE": 200,
  "MESSAGE": "Data returned for all CDN Hostnames for this CDN Zone.",
  "DATA": {
    "CDN_HOSTNAMES": [
      {
        "ID": 4021,
        "HOSTNAME": "video.zone.cg-cdn.com",
        "SSL_ENABLED": 1,
        "FORCE_SSL": 0,
        "DEFAULT": 1,
        "SSL_CERTIFICATE": "LETSENCRYPT",
        "CERTIFICATE_EXPIRES": 1796976000,
        "TIMESTAMP": 1789200000
      },
      {
        "ID": 4022,
        "HOSTNAME": "cdn.example.com",
        "SSL_ENABLED": 1,
        "FORCE_SSL": 1,
        "DEFAULT": 0,
        "SSL_CERTIFICATE": "LETSENCRYPT",
        "CERTIFICATE_EXPIRES": 1797062400,
        "TIMESTAMP": 1789203600
      }
    ]
  }
}

Add a hostname#

• HOSTNAMEStringrequireda full name of at least two labels, letters, digits and hyphens, up to 253 characters. No wildcard, no port, no IP address, no name containing cachegenie.com or cg-cdn.com, and not a name already on any zone.

curl -X POST https://api.cachegenie.com/v1/cdn/AB12CD34E/hostnames \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"HOSTNAME": "cdn.example.com"}'

The answer is the new hostname object with MESSAGE CDN Hostname Created.. It is created with SSL off, so that the DNS can be pointed at the zone first; switch SSL on afterwards and a certificate is issued. See Hostnames and certificates. Refusals, each a 400: Missing HOSTNAME in JSON Body., Invalid CDN Hostname., This CDN Hostname already exists, please try again.; a write that did not go through is 500 Unable to create CDN Hostname - Internal Server Error, please try again.

View a hostname#

One hostname object, MESSAGE CDN Hostname Data Returned.. A hostname that is not on this zone answers 404 CDN Hostname not found.

Update a hostname#

• SSL_ENABLEDIntegeroptional1 for on, any other value for off; left out or null, unchanged. The default hostname's SSL cannot be switched off; a request to do so is ignored. Switching SSL off switches FORCE_SSL off with it.
• FORCE_SSLIntegeroptional1 for on, any other value for off; left out or null, unchanged. On needs SSL on and a certificate that has not expired.

curl -X POST https://api.cachegenie.com/v1/cdn/AB12CD34E/hostnames/4022 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"SSL_ENABLED": 1, "FORCE_SSL": 1}'

The answer is the updated object with MESSAGE CDN Hostname Updated.. Asking for Force SSL before a certificate exists is 400 FORCE_SSL needs SSL_ENABLED and a certificate for the hostname (Let's Encrypt once issued, or an uploaded one); see SSL_CERTIFICATE and CERTIFICATE_EXPIRES on the hostname.: switch SSL on, wait for CERTIFICATE_EXPIRES to show a date in the future, then send FORCE_SSL.

Delete a hostname#

Removes the hostname and every certificate it had, at once. MESSAGE CDN Hostname Deleted. with an empty DATA. The default hostname cannot be deleted: 400 Unable to delete the Default CDN Hostname.

View the certificate#

MESSAGE CDN Hostname Certificate Returned. and four fields: TYPE (LETSENCRYPT or CUSTOM), ISSUER (the issuer's name; Let's Encrypt for ours), EXPIRES (Unix seconds, 0 when none is in place yet) and UPLOADED (when a custom certificate was uploaded, 0 for Let's Encrypt).

Upload your own certificate#

• CERTIFICATEStringrequiredthe certificate in PEM form, leaf first, intermediates after it. Up to 64 KB.
• PRIVATE_KEYStringrequiredthe matching key in PEM form, unencrypted. RSA of 2048 bits or more, or EC on P-256, P-384 or P-521 with a named curve. Up to 16 KB.

curl -X POST \
  https://api.cachegenie.com/v1/cdn/AB12CD34E/hostnames/4022/certificate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile c fullchain.pem --rawfile k privkey.pem \
        '{CERTIFICATE: $c, PRIVATE_KEY: $k}')"

The certificate has to cover the hostname (common name or a subject alternative name; a wildcard covers one label), be unexpired and not start more than a day in the future. Saving replaces any certificate the hostname had, the Let's Encrypt one included, switches SSL on, and puts it on every location within seconds. The answer is MESSAGE CDN Hostname Certificate Saved. with the certificate object above as DATA. A write that did not go through is 500 Unable to save the certificate - Internal Server Error, please try again. Refusals, each a 400 with the same sentence the NOC's upload popup shows:

• CERTIFICATE and PRIVATE_KEY (both PEM text) are required.
• The default hostname always uses Let's Encrypt; own certificates are for hostnames you added.
• Paste both the certificate and its private key.
• The certificate or key is larger than expected. Paste the PEM text only.
• The certificate must be PEM text starting with -----BEGIN CERTIFICATE-----.
• The certificate could not be read. Paste the PEM certificate exactly as it was issued.
• The private key is encrypted. Remove the passphrase and paste the unencrypted PEM key.
• The private key could not be read. It must be an unencrypted PEM key (RSA or EC).
• The private key does not belong to this certificate.
• RSA keys must be 2048 bits or longer.
• EC keys must use a named curve (P-256, P-384 or P-521) rather than explicit curve parameters. Export the key with named-curve parameters and try again.
• Only RSA and EC keys are supported.
• This certificate expired on {date}. Upload a current one.
• This certificate is not valid until {date}.
• This certificate is not issued for {hostname}. It covers {names}.

Remove your own certificate#

Deletes an uploaded certificate, switches FORCE_SSL off, and starts a Let's Encrypt issuance for the name. MESSAGE CDN Hostname Certificate Removed.. A hostname that has no uploaded certificate answers 404 This hostname has no own certificate; it uses Let's Encrypt., so a delete never silently switches Force SSL off on a Let's Encrypt hostname.