Help Center

  1. StackPath Help
  2. SSL
  3. Advanced User Guides

Requesting EdgeSSL Certificates via API

Avatar
Nassim Hacene-Chaouch
Updated:

Overview

To obtain the security benefits of using HTTPS on your site, you need an SSL certificate. 

Stackpath offers a free SSL certificate that covers the following scenarios when using the StackPath API:

  • Option 1: If your CDN site is delivered using an apex domain (example.com) or a www subdomain (www.example.com), then the free SSL certificate will cover both. 
    • This option will be described in Step 2, Option 1. 
  • Option 2: If your CDN Site is created under a subdomain (cdn.example.com, api.example.com), your free SSL certificate will only cover that subdomain. For sites with multiple subdomains, StackPath recommends that you create an individual site for each subdomain.
    • This option will be described in Step 2, Option 2. 
  • Option 3: If you enter the apex domain and all subdomains as a delivery domain then it is possible to create an SSL certificate. 

Step 1: Request an auth token

The API requires authentication tokens. Create a token with an API call to:

https://gateway.stackpath.com/identity/v1/oauth2/token.

The request's body must contain your "client_id" and "client_secret". This information was provided when you first set up API access through the StackPath Control Portal.  

Review the following full cURL sample request.  

  • This sample request contains 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"}'

Review the following sample response with the JSON object:

{
  "access_token": "this_is_your_token_and_its_around_700_characters",
  "token_type": "bearer",
  "expires_in": 3600
}
Tokens expire every hour, so if you use the API programmatically, you will need to refresh your token.

Step 2: Generate an SSL certificate

Generate an SSL certificate with a POST request to:

https://gateway.stackpath.com/cdn/v1/stacks/{stack_ID}/sites/{site_ID}/certificates/request

To locate your site ID and stack ID, access the StackPath Control Portal, and navigate to your site / stack. The ID for your site and stack will display in the URL. The first ID is your stack ID, the second is your site ID.

Review the following URL sample with displayed IDs:

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

Additionally, review the following body content to use with the request: 

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

Before you add any host to the request, you must add the host to the Delivery Domains list.

  • To learn how to add a delivery domain, see What is a Delivery Domain?.
  • If you leave hosts empty, then all of the delivery domains will be added. 
  • If the hosts parameter is not empty, then the first entry in the list will be used as the certificate common name, and then rest will be alternate names. 

Option 1: Apex domain and www. subdomain

Review the following full cURL sample request.

  • This sample request contains placeholder values. 
  • Additionally, this sample request contain an hosts object that takes 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"]}'

Review the following sample response. 

  • Note the information for dnsRecords. You will need this information for a later step. 
{
  "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."
        ]
      }
    }
  ]
} 

Option 2: Single customer subdomain

Review the following sample request to create an SSL certificate for a single subdomain:

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"]}'

Review the following sample response.

  • Note the information for dnsRecords. You will need this information for a later step. 
{
  "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."
        ]
      }
    }
  ]
}

Option 3: All delivery domains 

Review the following cURL request to add all subdomains and the apex domain:

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": []}'

Review the following sample response. 

  • Note the information for dnsRecords. You will need this information for a later step. 
{
  "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: Validate DNS

To complete this process, you must update your DNS provider to validate that you own the domain. 

Based on the response and the listed information for dnsRecords, create a CNAME record on the domain with the key as the name, and the value as the CNAME value. 

For example, based on the sample responses shown above:

  • _dbedeb4a1190d9074f979d2e6dff03c3 is the key.
  • ...b0abfe7a823ceb2542cf.448c2f86e64941008d53.comodoca.com. is the value.

(Optional) Step 4: Access verification details 

Option 1: Use the portal

To access these verification details in the future, browse to the certificate in the portal. 

  1. In the portal, in the left-side navigation menu, click Sites. 
  2. Locate and select the desired site.
    • This action will refresh the portal. 
  3. In the left-side navigation menu, click EdgeSSL.

Option 2: Use an API call

To access these verification details in the future, make a 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 the request to generate a certificate. 

Review the following full cURL sample request:

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'

Review the following sample response:

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

Related articles

Not finding what you need?

95% of questions can be answered using the search tool. This is the quickest way to get a response.

Contact Us