Guides

Requesting EdgeSSL Certificates

Overview

You can use the StackPath API to create a free EdgeSSL certificate that covers your CDN and/or WAF Site in the following scenarios:

  • Option 1: Create an EdgeSSL certificate that only covers specified Delivery Domains.
  • Option 2: Create an EdgeSSL certificate that covers all Delivery Domains.

To learn more, see Learn About Delivery Domains

Hosts

Hosts are also known as Delivery Domains that you can integrate with our CDN and/or WAF. HTTPS connections between a host and an end-user should be secured using an EdgeSSL certificate.

When creating an EdgeSSL certificate, all hosts must be added to your Site's list of Delivery Domains prior to making the request.

If you leave the hosts parameter empty, then all of your Site's Delivery Domains will be added to the certificate.

If the hosts parameter is not empty, then the first entry in the list will be used as the certificate common name, and the rest will be alternate names.

Verification Methods

The following methods are used to validate your EdgeSSL certificate:

  • DNS Challenge Validation: Create a CNAME record on your domain's DNS with a StackPath-generated string. StackPath will verify the record and then issue the SSL certificate.

  • HTTP Request Validation: Create a CNAME record to point your domains to either your Site's Edge Address or our anycast IP address. StackPath will verify the domains' ownership through an HTTP request.

Create an EdgeSSL Certificate

Option 1: Create an EdgeSSL certificate that only covers specified Delivery Domains

In the example request below, we are creating an EdgeSSL certificate using the DNS Challenge Validation method that will secure our two Delivery Domains, domain.com and www.domain.com.

Note that domain.com is listed first, so it is the common name and www.domain.com is an alternative name.

curl --request POST \
     --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/sites/SITE_ID/certificates/request \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
     "hosts": [
          "domain.com",
          "www.domain.com"
     ],
     "verificationMethod": "DNS"
}
'

The response will look similar to the following:

{
  "certificate": {
    "id": "f0ab6eaf-0f35-4f33-b8cf-c7e7530fc31f",
    "fingerprint": "",
    "commonName": "domain.com",
    "issuer": "",
    "caBundle": "",
    "trusted": false,
    "expirationDate": "2023-01-31T18:28:39.361337206Z",
    "createDate": "2023-01-31T18:28:39.362591337Z",
    "updateDate": "2023-01-31T18:28:39.771916138Z",
    "subjectAlternativeNames": [
      "domain.com",
      "www.domain.com"
    ],
    "status": "PENDING",
    "providerManaged": true
  },
  "verificationRequirements": [
    {
      "dnsVerificationDetails": {
        "dnsRecords": [
          "_acme-challenge.domain.com 120 IN CNAME 6648f76f-4779-436d-80b5-d0713260272c.stackpath-tls.com",
          "_acme-challenge.www.domain.com 120 IN CNAME 6648f76f-4779-436d-80b5-d0713260272c.stackpath-tls.com"
        ],
        "records": [
          {
            "name": "_acme-challenge.domain.com",
            "type": "CNAME",
            "class": "IN",
            "ttl": 120,
            "data": "6648f76f-4779-436d-80b5-d0713260272c.stackpath-tls.com."
          },
          {
            "name": "_acme-challenge.www.domain.com",
            "type": "CNAME",
            "class": "IN",
            "ttl": 120,
            "data": "6648f76f-4779-436d-80b5-d0713260272c.stackpath-tls.com."
          }
        ]
      },
      "verificationMethod": "DNS"
    }
  ]
}

Using the information provided under records, add the appropriate CNAME records to your DNS to complete the EdgeSSL certificate creation process.

Option 2: Create an EdgeSSL certificate that covers all Delivery Domains

In the example request below, we are creating an EdgeSSL certificate using the HTTP Request Validation method that will secure all of our Delivery Domains. To do this, we will omit the hosts parameter.

curl --request POST \
     --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/sites/SITE_ID/certificates/request \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
     "verificationMethod": "HTTP"
}
'

The response will look similar to the following:

{
  "certificate": {
    "id": "b30e369c-8580-4bc6-8fed-474700129337",
    "fingerprint": "",
    "commonName": "domain.com",
    "issuer": "",
    "caBundle": "",
    "trusted": false,
    "expirationDate": "2023-01-31T18:30:10.983817321Z",
    "createDate": "2023-01-31T18:30:10.985354955Z",
    "updateDate": "2023-01-31T18:30:11.371906376Z",
    "subjectAlternativeNames": [
      "domain.com",
      "www.domain.com",
      "cdn.domain.com",
      "api.domain.com"
    ],
    "status": "PENDING",
    "providerManaged": true
  },
  "verificationRequirements": [
    {
      "dnsVerificationDetails": {
        "dnsRecords": [
          "_acme-challenge.domain.com 120 IN CNAME 3bffa102-33eb-4140-9839-b025534e1a21.stackpath-tls.com",
          "_acme-challenge.www.domain.com 120 IN CNAME 3bffa102-33eb-4140-9839-b025534e1a21.stackpath-tls.com",
          "_acme-challenge.cdn.domain.com 120 IN CNAME 3bffa102-33eb-4140-9839-b025534e1a21.stackpath-tls.com",
          "_acme-challenge.api.domain.com 120 IN CNAME 3bffa102-33eb-4140-9839-b025534e1a21.stackpath-tls.com"
        ],
        "records": [
          {
            "name": "_acme-challenge.domain.com",
            "type": "CNAME",
            "class": "IN",
            "ttl": 120,
            "data": "3bffa102-33eb-4140-9839-b025534e1a21.stackpath-tls.com."
          },
          {
            "name": "_acme-challenge.www.domain.com",
            "type": "CNAME",
            "class": "IN",
            "ttl": 120,
            "data": "3bffa102-33eb-4140-9839-b025534e1a21.stackpath-tls.com."
          },
          {
            "name": "_acme-challenge.cdn.domain.com",
            "type": "CNAME",
            "class": "IN",
            "ttl": 120,
            "data": "3bffa102-33eb-4140-9839-b025534e1a21.stackpath-tls.com."
          },
      {
            "name": "_acme-challenge.api.domain.com",
            "type": "CNAME",
            "class": "IN",
            "ttl": 120,
            "data": "3bffa102-33eb-4140-9839-b025534e1a21.stackpath-tls.com."
          }
        ]
      },
      "verificationMethod": "DNS"
    }
  ]
}

Renewing SSL Certificates

SSL certificates that are uploaded to our platform, both third-party certificates and EdgeSSL certificates, are bound to the Stack where they were originally uploaded.

For example, if you are updating an expired wildcard SSL that is associated with multiple subdomains that are spread across multiple Stacks, you will have to to add your updated certificate to its original Stack.

📘

Any wildcard certificate that is uploaded to StackPath will automatically apply to all domains and subdomains listed on the certificate.

Updated about 2 months ago