Skip to content

Manage custom certificates

For use cases and limitations, refer to custom certificates.

Upload certificates

With the dashboard

To upload a custom certificate in the dashboard, follow the steps for issuing new certificates, but change the Certificate type to Custom certificate.

For more details on bundle method, refer to Bundle Methodologies

With the API

The call below will upload a certificate for use with app.example.com.

Note that if you are using an ECC key generated by OpenSSL, you will need to first remove the -----BEGIN EC PARAMETERS-----...-----END EC PARAMETERS----- section of the file.

1. Update the file and build the payload

Terminal window
cat app_example_com.pem
-----BEGIN CERTIFICATE-----
MIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E
...
SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O
OeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7
-----END CERTIFICATE-----
Terminal window
MYCERT="$(cat app_example_com.pem|perl -pe 's/\r?\n/\\n/'|sed -e 's/..$//')"
MYKEY="$(cat app_example_com.key|perl -pe 's/\r?\n/\\n/'|sed -e's/..$//')"

With the certificate and key saved to environment variables (using escaped newlines), build the payload:

Terminal window
$ echo $MYCERT
-----BEGIN CERTIFICATE-----\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\n-----END CERTIFICATE-----\n
$ request_body=$(< <(cat <<EOF
{
"hostname": "app.example.com",
"ssl": {
"custom_certificate": "$MYCERT",
"custom_key": "$MYKEY"
}
}
EOF
))

2. Upload your certificate and key

Use a POST request to upload your certificate and key.

The serial number returned is unique to the issuer, but not globally unique. Additionally, it is returned as a string, not an integer.


Move to a Cloudflare certificate

If you want to switch from maintaining a custom certificate to using one issued by Cloudflare, you can migrate that certificate with zero downtime.

Send a PATCH request to your custom hostname with a value for the DCV method. As soon as the certificate is validated and the hostname is validated, Cloudflare will remove the old custom certificate and begin serving the new one.