---
title: Manage custom certificates · Cloudflare SSL/TLS docs
description: This page lists Cloudflare requirements for custom certificates and explains how to upload and update these certificates using Cloudflare dashboard or API.
lastUpdated: 2024-12-16T22:33:26.000Z
source_url:
  html: https://zt-dark-mode-changelog.preview.developers.cloudflare.com/ssl/edge-certificates/custom-certificates/uploading/index.md
  md: https://zt-dark-mode-changelog.preview.developers.cloudflare.com/ssl/edge-certificates/custom-certificates/uploading/
---

This page lists Cloudflare requirements for custom certificates and explains how to upload and update these certificates using Cloudflare dashboard or API.

## Certificate requirements

Before accepting custom certificates, Cloudflare parses them and checks for validity according to a list of requirements.

***

## Upload a custom certificate

Warning

When using `compatible` or `modern` [bundling](https://developers.cloudflare.com/ssl/edge-certificates/custom-certificates/bundling-methodologies), make sure to upload only the leaf certificate. This will allow Cloudflare to properly handle [the expiration of intermediate and root certificates](https://developers.cloudflare.com/ssl/edge-certificates/custom-certificates/bundling-methodologies/#intermediate-and-root-certificates).

* Dashboard

  To upload a custom SSL certificate in the dashboard:

  1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.

  2. Select your application.

  3. Go to **SSL/TLS**.

  4. In **Edge Certificates**, select **Upload Custom SSL Certificate**.

  5. Copy and paste relevant values into **SSL Certificate** and **Private key** text areas (or select **Paste from file**).

     Note

     If doing this manually, include the `---BEGIN CERTIFICATE---` and `---END CERTIFICATE---` like the placeholder text.

  6. Choose the appropriate [**Bundle Method**](https://developers.cloudflare.com/ssl/edge-certificates/custom-certificates/bundling-methodologies/).

  7. Select a value for [**Private Key Restriction**](https://developers.cloudflare.com/ssl/edge-certificates/custom-certificates/#geo-key-manager-private-key-restriction).

  8. Select a value for **Legacy Client Support**, which specifies [Server Name Indication (SNI)](https://developers.cloudflare.com/ssl/reference/browser-compatibility/#non-sni-support) support:

     * **Modern (recommended)**: SNI only

     * **Legacy**: Supports non-SNI

       Warning

       Custom certificates of the type `legacy_custom` are not compatible with [BYOIP](https://developers.cloudflare.com/byoip/).

  9. Select **Upload Custom Certificate**. If you see an error for `The key you provided does not match the certificate`, contact your Certificate Authority to ensure the private key matches the certificate.

  10. (optional) [Add a CAA DNS record](https://developers.cloudflare.com/ssl/edge-certificates/caa-records/).

* API

  The following call will upload a certificate for use with `app.example.com`. Cloudflare will automatically bundle the certificate with a certificate chain optimized for maximum compatibility with browsers.

  Warning

  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

  ```sh
  cat app_example_com.pem
  ```

  ```sh
  -----BEGIN CERTIFICATE-----
  MIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN
  MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E
  ...
  SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O
  OeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7
  -----END CERTIFICATE-----
  ```

  ```sh
  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:

  ```bash
  request_body=$(< <(cat <<EOF
  {
    "certificate": "$MYCERT",
    "private_key": "$MYKEY",
    "bundle_method": "ubiquitous"
  }
  EOF
  ))
  ```

  You can optionally add [geographic restrictions](https://blog.cloudflare.com/introducing-cloudflare-geo-key-manager/) that specify where your private key can physically be decrypted:

  ```bash
  request_body=$(< <(cat <<EOF
  {
    "certificate": "$MYCERT",
    "private_key": "$MYKEY",
    "bundle_method": "ubiquitous",
    "geo_restrictions": {"label": "us"}'
  }
  EOF
  ))
  ```

  You can also enable support for legacy clients which do not include SNI in the TLS handshake.

  ```bash
  request_body=$(< <(cat <<EOF
  {
    "certificate": "$MYCERT",
    "private_key": "$MYKEY",
    "bundle_method": "ubiquitous",
    "geo_restrictions": {"label": "us"}',
    "type":"sni_custom"
  }
  EOF
  ))
  ```

  `sni_custom` is recommended by Cloudflare. Use `legacy_custom` when a specific client requires non-SNI support. The Cloudflare API treats all Custom SSL certificates as Legacy by default.

  Warning

  Custom certificates of the type `legacy_custom` are not compatible with [BYOIP](https://developers.cloudflare.com/byoip/).

  1. Upload your certificate and key

  Use the [POST](https://developers.cloudflare.com/api/resources/custom_certificates/methods/create/) endpoint to upload your certificate and key.

  ```bash
  curl https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_certificates \
  --header "X-Auth-Email: <EMAIL>" \
  --header "X-Auth-Key: <API_KEY>" \
  --header "Content-Type: application/json" \
  --data "$request_body"
  ```

  1. (Optional) Add a CAA record.

  A Certificate Authority Authorization (CAA) DNS record specifies which certificate authorities (CAs) are allowed to issue certificates for a domain. This record reduces the chance of unauthorized certificate issuance and promotes standardization across your organization.

  For more guidance, refer to [Create a CAA record](https://developers.cloudflare.com/ssl/edge-certificates/caa-records/).

***

## Update an existing custom certificate

Before you update an existing custom certificate, you might want to consider having active [universal](https://developers.cloudflare.com/ssl/edge-certificates/universal-ssl/) or [advanced](https://developers.cloudflare.com/ssl/edge-certificates/advanced-certificate-manager/) certificates as fallback options. Go to [**SSL/TLS** > **Edge Certificates**](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/edge-certificates) to check a list of hostnames and status of the edge certificates in your zone.

If you are on an Enterprise plan and want to update a custom (modern) certificate, also consider requesting access to [Staging environment (Beta)](https://developers.cloudflare.com/ssl/edge-certificates/staging-environment/).

Replacing a custom certificate following these steps does not lead to any downtime. No connections will be terminated and new connections will use the new certificate. The old certificate will only actually be deleted when the new certificate is uploaded and active.

* Dashboard

  To update a certificate in the dashboard:

  1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
  2. Select your application.
  3. Go to **SSL/TLS**.
  4. In **Edge Certificates**, locate a custom certificate.
  5. Select the wrench icon and select **Replace SSL certificate and key**.
  6. Follow the same steps as [upload a new certificate](#upload-a-custom-certificate).

* API

  To update a certificate using the API, send a [`PATCH`](https://developers.cloudflare.com/api/resources/custom_certificates/methods/edit/) command.

Note

To update the **Private Key Restriction** setting of a certificate, delete and re-add the certificate.
