API Reference

Custom Certificates

Getting started

Custom certificates are designed for customers across all plans who want to use their own SSL certificates, offering greater control and customization options to fit specific needs.

Unlike BrandSSL-issued certificates, where we manage issuance and renewal, with custom certificates, customers are in charge of the following actions:

  • Uploading the Certificate: You need to add your custom certificate to your account through the BrandSSL dashboard or the API.

  • Updating the Certificate: Should there be any changes to the SSL certificate, such as renewals, you are responsible for updating it on the BrandSSL platform.

  • Monitoring the Certificate Expiration Date: It's important to track your certificate's expiration date otherwise your visitors may not be able to connect due to an expired certificate. BrandSSL will not automatically renew custom certificates.

👍

Availability

BrandSSL Custom SSL is available on all plans.


The remainder of this guide provides instructions on how to upload, update, and manage custom certificates on BrandSSL.


Custom certificate requirements

Before accepting custom certificates, BrandSSL parses them and checks for validity according to a list of requirements. These checks ensure that your certificate is valid. The uploaded custom certificates must meet all the following requirements:

  • Be Encoded in PEM Format: Your custom certificate should be encoded in PEM format
  • Have a Subject Alternative Name (SAN) Matching the domain name it is being added to
  • Not Be Expiring in Less Than 14 Days from the Time of Upload
  • Not Have a Key File Password: The private key used with your certificate should not have a password. BrandSSL will not be able to parse your certificate if the key is password-protected.

Adding a custom certificate

Here is the process of adding your custom SSL certificate via the BrandSSL dashboard:

  • Prepare your SSL certificate: You should have your SSL Certificate and the corresponding Private Key ready. Ensure that the SSL Certificate is in PEM format and contains the full certificate chain
  • Go to Domains
  • In Domains select the relevant domain
  • Select Add certificate
  • Copy and paste relevant values into SSL Certificate and Private key inputs (or drag and drop the files).
  • Click on Next and the uploaded certificate will be validated. Incorrect or expired certificates will not be accepted. The certificate and the private key should match, and the certificate should be issued for the domain you have specified.

Removing a custom certificate

Here is the process of removing a custom SSL certificate via the BrandSSL dashboard:

  • Go to Domains
  • In Domains select the relevant domain
  • Select Remove certificate

Managing certificates via the API

BrandSSL also offers an API for managing your certificates programmatically. You can add, update, and remove your certificates using the API.

Here are the API calls that you can use:

📘

API KEY

Replace the API_KEY with your BrandSSL token. You can get your authorization token from the settings page of your dashboard.


Adding a certificate

curl -X POST -H "Content-type: application/json" -d '{
    "display_name": "optional name",
    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    "domain": "example.com"
}' 'https://www.brandssl.io/api/{API_KEY}/certificate/add'

If the request is successful, you will get an HTTP status 201 response.

Updating a certificate

curl -X POST -H "Content-type: application/json" -d '{
    "display_name": "optional name",
    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    "domain": "example.com"
}' 'https://www.brandssl.io/api/{API_KEY}/certificate/update'

If the request is successful, you will get an HTTP status 201 response.

Removing a certificate

curl -X POST -H "Content-type: application/json" -d '{
    "domain": "example.com"
}' 'https://www.brandssl.io/api/{API_KEY}/certificate/remove'

If the request is successful, you will get an HTTP status 200 response.