Requesting EdgeSSL Certificates via API Call

Avatar
Nassim Hacene-Chaouch
Updated:
Follow

You'll need an SSL certificate to get the security benefits of using https on your site. Stackpath offers a free SSL certificate that will cover the following scenarios when using the StackPath API:

  • Scenario 1: If your StackPath CDN site is delivered using an apex domain (example.com) or the www subdomain (www.example.com), the Free SSL will be cover both.
  • Scenario 2: If your StackPath CDN site is created under a subdomain (cdn.example.com, api.example.com), your free SSL certificate will cover only that subdomain. For sites with multiple subdomains, we recommend creating an individual site for each subdomain.
  • Scenario 3: It is possible to create an SSL certificate for the apex domain and all subdomains entered as a Delivery Domain.

Step 1: Request an Auth Token

The API requires authentication tokens, which are created with an API call towards https://gateway.stackpath.com/identity/v1/oauth2/token. The body of that request should contain the "client_id" and "client_secret" that was provided when setting up API access through the StackPath Control Portal. Below is a full cURL example using placeholder values:


curl --request POST \
 --url https://gateway.stackpath.com/identity/v1/oauth2/token \
 --header 'content-type: application/json' \
 --data '{"client_id": "e7f729f458a1abf7b56b3fefe06c2023", "client_secret": "75b27684d973e6f51c6d5e8af8af5328991503e27e2e14dfe5a920a9ae12a8b7", "grant_type": "client_credentials"}'

This should produce a response with the following JSON object:

{
  "access_token": "this_is_your_token_and_its_around_700_characters",
  "token_type": "bearer",
  "expires_in": 3600
}
Remember tokens expire every hour, so if you're using the API programmatically you will need to refresh your token!

Step 2: Generate an SSL certificate

To generate the SSL certificate, you need to make a POST request to https://gateway.stackpath.com/cdn/v1/stacks/{stack_ID}/sites/{site_ID}/certificates/request

You can find your site ID and stack ID in the URL when using the portal if you're browsing the site/stack in question. Here's an example URL:

/stacks/bb39f208-6131-45cr-80e0-26c766f70cfb/cdn/sites/208bb244-1b7e-4e3f-9226-cefce6c4140b/

The first ID is your stack ID, the second is your site ID

You'll also need to send body content with this request, here's the format:

{ "hosts": [ "string",  "string", "string", ] }

Please note that any "hosts" added here will need to be added to the Delivery Domains list beforehand. If "hosts" is left empty, all of the delivery domains will be added. If the "hosts" parameter is not empty the first entry in the list will be used as the certificate common name, and the rest will be alternative names.

Scenario 1: Apex domain and www. domain

Here's a full cURL example of this request, with placeholder values and an "hosts" object that will take the first item (apex domain) as the common name, and the second item (www subdomain) as an alternate name:

curl --request POST \
 --url https://gateway.stackpath.com/cdn/v1/stacks/cc48f116-6131-45be-80e0-26c766f70bcf/sites/208cc255-2c7e-5b3f-7227-cefce7c4140b/certificates/request \
 --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyHabWQiOiJodHRwczovL2dhdGV3YXkuc3RhY2twYXRoLmNvbSIsImV4cCI6MTU0ODM0OTM4MCwiaWF0IjoxMNQ4MzQ1NzgwLCJpc3MiOiJpZGVudGl0eS5zdGFja3BhdGguY29tIiwic3ViIjoic3RhY2twYXRofDYyM2ZiOTdlLThhZYntNDc4Yy04MDg0LWE2MmY2MWZjODM2YSIsImh0dHBzOi8vaWRlbnRpdHkuc3RhY2twYXRoLmNvbS9hY2NvdW50cyI6W3siaWQiOiI5MDBmODk2OS05YWJmLTRiZmQtYTlmNS1kOGY2NWZlZmM3MjUifV19.c94XU9d6GQ4wnCTDIGBVErPITOODiaE6PiRVUz4prMyhkpY87-m-_G-ZC8grFzJNG8F5rmSnrtC9R1jZ9zOrRzVDzFTE2g29PicXiSV-yNsRMW7HTQOYQoIlYpcvrwGVJuaENu6lYsszpBBeC-1JoMAiGRTRTIGiY2pvV6Sx2vc2FtdXXNa4hRwy_MOnipSFKL2ifQj0OyYJsQDhswOPsEBqhnaaSR-U4sDsN4ASxoYsHEzM8cPmfEdcjDozEZWHY1mhf6XaBSyni42QaBiRDyjykCsjJ4u9M30uXmJmuAl5znhA8xxQmuzkcST1PkdgdLB8odNJmIBiYfdtB-7Bdw' \
 --header 'content-type: application/json' \
 --data '{"hosts": ["test.cf", "www.test.cf"]}'

Example response:

{
  "certificate": {
    "id": "1dfd707b-2026-52b1-86ba-addf145cdf7c",
    "commonName": "test.cf",
    "expirationDate": "2019-01-24T16:35:44.362972481Z",
    "createDate": "2019-01-24T16:35:44.363668879Z",
    "updateDate": "2019-01-24T16:35:45.345945442Z",
    "subjectAlternativeNames": [
     "www.test.cf"
    ],
    "status": "PENDING",
    "providerManaged": true
  },
  "verificationRequirements": [
    {
      "dnsVerificationDetails": {
        "dnsRecords": [
          "_dbedeb4a1190d9074f979d2e6dff03c3 120 IN CNAME 4f02b6ed1bbfbdbc472549ff35c50dd9.e15464f68b83b0abfe7a823ceb2542cf.448c2f86e64941008d53.comodoca.com."
        ]
      }
    }
  ]
} 

Scenario 2: Single customer subdomain

For our second scenario, we're going to create an SSL certificate for a single subdomain. Here's the cURL request:

curl --request POST \
 --url https://gateway.stackpath.com/cdn/v1/stacks/cc48f116-6131-45be-80e0-26c766f70bcf/sites/208cc255-2c7e-5b3f-7227-cefce7c4140b/certificates/request \
 --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyHabWQiOiJodHRwczovL2dhdGV3YXkuc3RhY2twYXRoLmNvbSIsImV4cCI6MTU0ODM0OTM4MCwiaWF0IjoxMNQ4MzQ1NzgwLCJpc3MiOiJpZGVudGl0eS5zdGFja3BhdGguY29tIiwic3ViIjoic3RhY2twYXRofDYyM2ZiOTdlLThhZYntNDc4Yy04MDg0LWE2MmY2MWZjODM2YSIsImh0dHBzOi8vaWRlbnRpdHkuc3RhY2twYXRoLmNvbS9hY2NvdW50cyI6W3siaWQiOiI5MDBmODk2OS05YWJmLTRiZmQtYTlmNS1kOGY2NWZlZmM3MjUifV19.c94XU9d6GQ4wnCTDIGBVErPITOODiaE6PiRVUz4prMyhkpY87-m-_G-ZC8grFzJNG8F5rmSnrtC9R1jZ9zOrRzVDzFTE2g29PicXiSV-yNsRMW7HTQOYQoIlYpcvrwGVJuaENu6lYsszpBBeC-1JoMAiGRTRTIGiY2pvV6Sx2vc2FtdXXNa4hRwy_MOnipSFKL2ifQj0OyYJsQDhswOPsEBqhnaaSR-U4sDsN4ASxoYsHEzM8cPmfEdcjDozEZWHY1mhf6XaBSyni42QaBiRDyjykCsjJ4u9M30uXmJmuAl5znhA8xxQmuzkcST1PkdgdLB8odNJmIBiYfdtB-7Bdw' \
 --header 'content-type: application/json' \
 --data '{"hosts": ["cdn.test.cf"]}'

Example response:

{
  "certificate": {
    "id": "1dfd707b-2026-52b1-86ba-addf145cdf7c",
    "commonName": "cdn.test.cf",
    "expirationDate": "2019-01-24T16:35:44.362972481Z",
    "createDate": "2019-01-24T16:35:44.363668879Z",
    "updateDate": "2019-01-24T16:35:45.345945442Z",
    "subjectAlternativeNames": [],
    "status": "PENDING",
    "providerManaged": true
  },
  "verificationRequirements": [
    {
      "dnsVerificationDetails": {
        "dnsRecords": [
          "_dbedeb4a1190d9074f979d2e6dff03c3 120 IN CNAME 4f02b6ed1bbfbdbc472549ff35c50dd9.e15464f68b83b0abfe7a823ceb2542cf.448c2f86e64941008d53.comodoca.com."
        ]
      }
    }
  ]
}

Scenario 3: All delivery domains 

In our last scenario, we're going to add all of our subdomains along with our apex domain. As mentioned above, to do this we just need to leave the "hosts" object empty. Here's the cURL request:

curl --request POST \
 --url https://gateway.stackpath.com/cdn/v1/stacks/cc48f116-6131-45be-80e0-26c766f70bcf/sites/208cc255-2c7e-5b3f-7227-cefce7c4140b/certificates/request \
 --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyHabWQiOiJodHRwczovL2dhdGV3YXkuc3RhY2twYXRoLmNvbSIsImV4cCI6MTU0ODM0OTM4MCwiaWF0IjoxMNQ4MzQ1NzgwLCJpc3MiOiJpZGVudGl0eS5zdGFja3BhdGguY29tIiwic3ViIjoic3RhY2twYXRofDYyM2ZiOTdlLThhZYntNDc4Yy04MDg0LWE2MmY2MWZjODM2YSIsImh0dHBzOi8vaWRlbnRpdHkuc3RhY2twYXRoLmNvbS9hY2NvdW50cyI6W3siaWQiOiI5MDBmODk2OS05YWJmLTRiZmQtYTlmNS1kOGY2NWZlZmM3MjUifV19.c94XU9d6GQ4wnCTDIGBVErPITOODiaE6PiRVUz4prMyhkpY87-m-_G-ZC8grFzJNG8F5rmSnrtC9R1jZ9zOrRzVDzFTE2g29PicXiSV-yNsRMW7HTQOYQoIlYpcvrwGVJuaENu6lYsszpBBeC-1JoMAiGRTRTIGiY2pvV6Sx2vc2FtdXXNa4hRwy_MOnipSFKL2ifQj0OyYJsQDhswOPsEBqhnaaSR-U4sDsN4ASxoYsHEzM8cPmfEdcjDozEZWHY1mhf6XaBSyni42QaBiRDyjykCsjJ4u9M30uXmJmuAl5znhA8xxQmuzkcST1PkdgdLB8odNJmIBiYfdtB-7Bdw' \
 --header 'content-type: application/json' \
 --data '{"hosts": []}'

Example response:

{
  "certificate": {
    "id": "1dfd707b-2026-52b1-86ba-addf145cdf7c",
    "commonName": "test.cf",
    "expirationDate": "2019-01-24T16:35:44.362972481Z",
    "createDate": "2019-01-24T16:35:44.363668879Z",
    "updateDate": "2019-01-24T16:35:45.345945442Z",
    "subjectAlternativeNames": ["www.test.cf", "cdn.test.cf"],
    "status": "PENDING",
    "providerManaged": true
  },
  "verificationRequirements": [
    {
      "dnsVerificationDetails": {
        "dnsRecords": [
          "_dbedeb4a1190d9074f979d2e6dff03c3 120 IN CNAME 4f02b6ed1bbfbdbc472549ff35c50dd9.e15464f68b83b0abfe7a823ceb2542cf.448c2f86e64941008d53.comodoca.com."
        ]
      }
    }
  ]
}

Step 3: DNS Validation

Please document the "dnsRecords" key/value shown in your results. In order to complete this process, you will need to update your DNS provider to validate you have ownership over the domain.

Please create a CNAME record on the domain with the key as the name, and the value as the CNAME value.

In the above example,
_dbedeb4a1190d9074f979d2e6dff03c3 is the key
...b0abfe7a823ceb2542cf.448c2f86e64941008d53.comodoca.com. is the value

Step 4 (Optional): Access verification details via API if needed

If you need to access these verification details later, you can do so by browsing to the certificate in the portal (under EdgeSSL in CDN sites).

You can also get these verification details using another GET API call to:

/cdn/v1/stacks/{stack_id}/certificates/{certificate_id}/verification_details

The {certificate_id} will be the "id" value from the JSON output from our request to generate the certificate. 

Full cURL example:

curl --request GET \
 --url https://gateway.stackpath.com/cdn/v1/stacks/cc48f116-6131-45be-80e0-26c766f70bcf/certificates/1dfd707b-2026-52b1-86ba-addf145cdf7c/verification_details \
 --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyHabWQiOiJodHRwczovL2dhdGV3YXkuc3RhY2twYXRoLmNvbSIsImV4cCI6MTU0ODM0OTM4MCwiaWF0IjoxMNQ4MzQ1NzgwLCJpc3MiOiJpZGVudGl0eS5zdGFja3BhdGguY29tIiwic3ViIjoic3RhY2twYXRofDYyM2ZiOTdlLThhZYntNDc4Yy04MDg0LWE2MmY2MWZjODM2YSIsImh0dHBzOi8vaWRlbnRpdHkuc3RhY2twYXRoLmNvbS9hY2NvdW50cyI6W3siaWQiOiI5MDBmODk2OS05YWJmLTRiZmQtYTlmNS1kOGY2NWZlZmM3MjUifV19.c94XU9d6GQ4wnCTDIGBVErPITOODiaE6PiRVUz4prMyhkpY87-m-_G-ZC8grFzJNG8F5rmSnrtC9R1jZ9zOrRzVDzFTE2g29PicXiSV-yNsRMW7HTQOYQoIlYpcvrwGVJuaENu6lYsszpBBeC-1JoMAiGRTRTIGiY2pvV6Sx2vc2FtdXXNa4hRwy_MOnipSFKL2ifQj0OyYJsQDhswOPsEBqhnaaSR-U4sDsN4ASxoYsHEzM8cPmfEdcjDozEZWHY1mhf6XaBSyni42QaBiRDyjykCsjJ4u9M30uXmJmuAl5znhA8xxQmuzkcST1PkdgdLB8odNJmIBiYfdtB-7Bdw'

Response:

{
  "verificationRequirements": [
    {
      "dnsVerificationDetails": {
        "dnsRecords": [
          "_dbedeb4a1190d9074f979d2e6dff03c3 120 IN CNAME 4f02b6ed1bbfbdbc472549ff35c50dd9.e15464f68b83b0abfe7a823ceb2542cf.448c2f86e64941008d53.comodoca.com."
        ]
      }
    }
  ]
}

If you have any questions or need further assistance with your EdgeSSL certificate, feel free to reach out to our 24/7 support team via live chat.

Was this article helpful?

Related articles