Secure Provisioning Service API Use Cases

The following are use cases for the Secure Provisioning Service API:

Action Operation Endpoint
Create OV SAN Certificate and Edge Hostname POST /config-secure-provisioning-service/v1/sps-requests/(?contractId&groupId)
Create a DV SAN Certificate with Edge Hostname and Prove Control over the Domain POST /config-secure-provisioning-service/v1/sps-requests/(?contractId&groupId)
Add a Domain Name to a SAN Certificate POST /config-secure-provisioning-service/v1/sps-requests/(?contractId&groupId)
Retrieve Information About the Request GET /config-secure-provisioning-service/v1/sps-requests/(?contractId&groupId)
Create a Secure Edge Hostname with an Existing Certificate POST /config-secure-provisioning-service/v1/secure-edge-hosts/(?contractId&groupId)

SPS Workflows

There are three common SPS workflows. You can:

  • Create a new certificate and secure edge hostname

  • Modify a SAN certificate and secure edge hostname

  • Create a secure edge hostname for an existing certificate

Creating a New Certificate and a Secure Edge Hostname

If you want to create a new single, wildcard, or SAN certificate and secure edge hostname, follow these general steps:

  1. You collect all the information you need to get a certificate. This includes the name, address, and phone number of your organization. Also, collect any information about any deployed secure edge hostnames.

  2. You send a request to SPS with all the information needed to create a certificate and create a secure edge hostname.

  3. SPS does some basic validation, then sends a request to CPS to create a certificate.

  4. CPS validates the request information and sends a certificate signing request (CSR) to the CA.

  5. The CA validates that you own your domains if you use domain validation, or that you are the company you say you are, if you use organization validation.

  6. CPS deploys the certificate to the Akamai network. While CPS processes the certificate, SPS intermittently polls CPS to check the status of the certificate.

  7. SPS sends a request to the internal Secure Edge Host API after CPS finishes deploying the certificate. If the requested name of the secure edge hostname is in use, SPS does not create a secure edge hostname, but the certificate is still available. If the secure edge hostname is in use, SPS marks the request to indicate that the edge hostname is already created or pending, and SPS does not take any further action.

  8. The Secure Edge host API validates the request information and creates a new edge hostname on the Akamai network using the new certificate.

  9. When SPS detects that the Secure Edge Host API created a secure edge hostname on the Akamai network, SPS marks the request as complete.

  10. You check the status of the request until SPS returns “SPS request complete”.

Modifying a SAN Certificate and Secure Edge Hostname

If you want to modify a SAN certificate and secure edge hostname, follow these general steps:

  1. You collect all the information you need to modify a certificate. This includes the name, address, and phone number of your organization. Also, collect any information about any deployed secure edge hostnames.

  2. You send a request to SPS with all the information needed to modify the SAN certificate and create a secure edge hostname.

  3. SPS validates the information, then sends a request to CPS to modify the specified SAN certificate.

  4. CPS validates the request information and sends a new certificate signing request (CSR) to the CA.

  5. The CA validates that you own your domains if you use domain validation, or that you are the company you say you are, if you use organization validation.

  6. CPS deploys the certificate to the Akamai network. While CPS processes the certificate, SPS intermittently polls CPS to check the status of the certificate.

  7. SPS sends a request to the internal Secure Edge Host API after CPS deploys the certificate. If the requested name of the secure edge hostname is in use, SPS does not create a secure edge hostname, but the certificate is still available. If the secure edge hostname is in use, SPS marks the request as “edge host already created or pending” and does not take any further action.

  8. The Secure Edge Host API validates the request information and creates a new edge hostname on the Akamai network using the modified certificate. While the Secure Edge Host API processes the request, SPS intermittently polls the Secure Edge Host API to check the status of the secure edge hostname.

  9. When SPS detects that the Secure Edge Host API created a secure edge hostname on the Akamai network, SPS marks the request as “SPS request complete”.

Creating a Secure Edge Hostname for an Existing Certificate

If you want to create a secure edge hostname for an existing certificate, you should follow these general steps:

  1. Collect all the information you need about the existing certificate in order to associate it with your new secure edge hostname. Also, collect any information about any deployed secure edge hostnames.

  2. Send a request to SPS with all the information needed to create a new secure edge hostname.

  3. SPS validates the information, then sends a request to the internal Secure Edge Host API. If the requested name of the secure edge hostname is in use, SPS does not create a secure edge hostname, but marks the request as “edge host already created or pending”

  4. The Akamai network processes the request and creates a secure edge hostname. While the Secure Edge Host API processes the request, SPS intermittently polls the Secure Edge Host API to check the status of the secure edge hostname. When SPS detects that the Secure Edge Host API created a secure edge hostname on the Akamai network, the SPS marks the request as “SPS request complete”.

Assumptions

These use cases assume the following:

  • the contractId is 11754

  • the groupId is 1001

  • the organization has both the Alta and WAA products. Given this, the product parameter is required. In these use cases the value of this parameter is alta.

  • the URL-encoded file shown in each use case will show only the fields you need to enter for the type of certificate you are creating or modifying.

  • HOST is the OPEN BASE_URL for your API.

NOTE: The examples in these use cases are in egcurl, which is a Python script used with curl for authorizing OPEN API clients on the Akamai network. For more information, see Authorize Your Client.

Endpoints

This API includes the following endpoints:

  • The sps-requests endpoint enables a customer to create a certificate and a secure edge hostname.

  • The secure-edge-hosts endpoint allows a customer to reference one of the following in order to create a secure edge hostname directly.

  • jobId: The job-specific ID received from either a completed SPS request, or from the Certificate Provisioning System (CPS).

  • enrollmentId: The ID that includes slot and certificate information received from either a completed SPS request, or from the Certificate Provisioning System (CPS).

SPS Requests Endpoint

The SPS Requests endpoint allows you either to create a certificate and a secure edge hostname, add a domain name to an existing certificate and create a secure edge hostname, or view information about existing SPS requests. A secure edge hostname is a host for each of your sites or applications that resolves to an Akamai domain. The format of a secure edge hostname is <your-chosen-name>.edgekey.net. In the SPS API, you specify <your-chosen-name> in the cnameHostname parameter. For example, if your cnameHostname is www.example.com, it points to the Akamai edge hostname, www.example.com.edgekey.net, which in turn resolves to individual servers on the Akamai network.

Creating an SPS Request

When an SPS request is created, a URL-encoded form is passed with all the information needed to provision both a certificate and a secure edge hostname. Your ability to create a specific type of certificate (single, wildcard, or SAN) is based on your contract, group, certificate usage, and quota. In the request you can also:

  • modify or reference an existing SAN certificate

  • configure a new secure edge hostname.

Certificate Options

Certificate Type createType validationType subscription-sni-only csr.sans
OV Single single ov NA NA
OV Single SNI single ov subscription-sni-only=true NA
OV SAN (example below) san ov NA include
OV SAN SNI san ov subscription-sni-only=true include
OV Wildcard wildcard ov NA NA
OV Wildcard SNI wildcard ov subscription-sni-only=true NA
DV SAN san dv NA include
DV SAN SNI san dv subscription-sni-only=true include

Create OV SAN Certificate and Edge Hostname

This use case takes you through the process of creating a new OV SAN certificate, a secure edge hostname. It also shows you how to prove control over the domain.

To create a new OV SAN certificate, run the following POST operation:

$ python egcurl -k -X POST 'HOST/config-secure-provisioning-service/v1/sps-requests/?contractId=11754&groupId=1001' --data @formparams

with a URL-encoded file called formparams which is for a new SAN certificate:

cnameHostname=www.example.cname-hostname300.com&createType=san&csr.cn=www.example.com&csr.ou=IT&csr.sans=www.example.com&csr.sans=www.new-example.com&csr.sans=www.example.net&csr.sans=www.new-example.net&organization-information.organization-name=My+Example+Inc.&organization-information.address-line-one=8+Cambridge+Center&organization-information.city=Cambridge&organization-information.region=MA&organization-information.postal-code=02136&organization-information.country=US&organization-information.phone=18008008000&admin-contact.first-name=Mary&admin-contact.last-name=Jones&admin-contact.phone=18008008001&admin-contact.email=m.jones@akamai.com&product=alta&validationType=ov

Response body with a 202 HTTP status:

{
   "Results" : {
      "data" : [
         {
            "code" : null,
            "data" : null,
            "message" : null,
            "results" : {
               "enrollmentId" : 54321,
               "jobID" : 67890,
               "type" : "SUCCESS"
            },
            "text" : null
         }
      ],
      "size" : 1
   },
   "resourceLocation" : "/config-secure-provisioning-service/v1/sps-requests/12345",
   "spsId" : 12345
}

NOTE: As this is a new SAN certificate, the csr.sans parameter is included.

Verify that the SPS request has completed successfully by seeing that the status is “SPS Request Complete”:

$ python egcurl -k -X GET 'HOST/config-secure-provisioning-service/v1/sps-requests/12345/?contractId=11754&groupId=1001'
{
   "requestList" : [
      {
         "enrollmentId" : 54321,
         "jobId" : 67890,
         "lastStatusChange" : "2015-10-13T19:31:35Z",
         "resourceUrl" : "/config-secure-provisioning-service/v1/sps-requests/12345",
         "spsId" : 12345,
         "status" : "SPS Request Complete",
         "workflowProgress" : "All of your requested changes are complete."
      }
   ]
}

Create a DV SAN Certificate with Edge Hostname and Prove Control over the Domain

This use case takes you through the process of creating a new DV SAN certificate and a secure edge hostname, in addition to completing domain validation.

To create a new SAN certificate, run the following POST operation:

$ python egcurl -k -X POST 'HOST/config-secure-provisioning-service/v1/sps-requests/?contractId=11754&groupId=1001' --data @formparams

with a URL-encoded file called formparams which is for a new SAN certificate:

cnameHostname=www.example.cname-hostname300.com&issuer=symantec&createType=san&csr.cn=www.example.com&csr.ou=IT&csr.sans=www.example.com&csr.sans=www.new-example.com&csr.sans=www.example.net&csr.sans=www.new-example.net&organization-information.organization-name=My+Example+Inc.&organization-information.address-line-one=8+Cambridge+Center&organization-information.city=Cambridge&organization-information.region=MA&organization-information.postal-code=02136&organization-information.country=US&organization-information.phone=18008008000&admin-contact.first-name=Mary&admin-contact.last-name=Jones&admin-contact.phone=18008008001&admin-contact.email=m.jones@akamai.com&product=alta&validationType=dv

Response body with a http status 202

{
   "Results" : {
      "data" : [
         {
            "code" : null,
            "data" : null,
            "message" : null,
            "results" : {
               "enrollmentId" : 54321,
               "jobID" : 67890,
               "type" : "SUCCESS"
            },
            "text" : null
         }
      ],
      "size" : 1
   },
   "resourceLocation" : "/config-secure-provisioning-service/v1/sps-requests/12345",
   "spsId" : 12345
}

NOTE: As this is a new SAN certificate, the csr.sans parameter is included.

Check the status of the SPS request:

$ python egcurl -k -X GET 'HOST/config-secure-provisioning-service/v1/sps-requests/12345/?contractId=11754&groupId=1001'
{
   "requestList" : [
      {
         "dvStatus" : [
            {
               "domainName" : "www.example.com",
               "expiresTimestamp" : "2016-07-21T16:11:02Z",
               "fullPath" : "http://www.sps-waa-san-le-cname-dcv-11.webexp-ipqa1.com/.well-known/acme-challenge/xaUZ3KKOhYhuUlcWvRB5-H9qHe8Hyyi0aSmSeDGUnSc&sa=D&usg=AFQjCNHS-Xhs61wpqvn94agpeMt-JdahHg",
               "redirectFullPath" : "http://dcv.akamai.com/.well-known/acme-challenge/www.example.com/xaUZ3KKOhYhuUlcWvRB5-H9qHe8Hyyi0aSmSeDGUnSc",
               "requestTimestamp" : "2015-09-23T22:33:25Z",
               "responseBody" : "eyJqd2siOnsia3R5IjoiUlNBIiwibiI6 ... m0RPsWDkjapoH7WyJ2KjiGTm4PUrv-qA",
               "status" : "Awaiting user",
               "token" : "xaUZ3KKOhYhuUlcWvRB5-H9qHe8Hyyi0aSmSeDGUnSc",
               "validatedTimestamp" : "2015-09-25T16:11:03Z"
            }
         ],
         "jobId" : 67890,
         "lastStatusChange" : "2015-09-25T19:49:19Z",
         "resourceUrl" : "/config-secure-provisioning-service/v1/sps-requests/12345",
         "spsId" : 12345,
         "status" : "CPS Running",
         "workflowProgress" : "All of your requested changes are complete."
      }
   ]
}

Prove control of the domain using one of three options:

Option #1: CNAMEed to *.edgekey.net

If your domain is CNAMEed to *.edgekey.net and if you are adding that domain name to an existing certificate, the challenge completes automatically. Check that each domain has a status of “valid” by performing an HTTP GETon the request.

Option #2: use redirects to complete the challenge:

  1. Each domain will have a unique dvStatus JSON object returned from the HTTP GET operation. Take note of the dvStatus.fullPath and dvStatus.redirectPath for each domain that needs to be validated.

    fullPath example:

    http://www.example.com/.well-known/acmechallenge/](http://www.example.com/.well-known/acme-challenge/0uYE2IaeO2qK8ZPsR5TJO_hFBNXtmweZvxwOCVZrzFF&sa=D&usg=AFQjCNHrYAu23Z1xYW5ReD13JYb3QnPcbQ0uYE2IaeO2qK8ZPsR5TJO_hFBNXtmweZvxwOCVZrzFF
    

    redirectFullPath example:

    http://dcv.akamai.com/.well-known/acme-challenge/](http://dcv.akamai.com/.well-known/acme-challenge/0uYE2IaeO2qK8ZPsR5TJO_hFBNXtmweZvxwOCVZrzFF&sa=D&usg=AFQjCNF1hEPHbmcc5K6TF9hsQt48FFdX1A0uYE2IaeO2qK8ZPsR5TJO_hFBNXtmweZvxwOCVZrzFF
    
  2. Configure your web server to redirect validation requests to Akamai. For each domain that needs to be validated, redirect requests from the fullPath address to the redirectPath address.

  3. Akamai will periodically poll the fullPath URL to confirm that it is serving the challenge token. When Akamai recognizes that the challenge token is being served, Akamai will programmatically instruct the CA to perform validation of the domain. This process is expected to take several minutes but less than one hour.

  4. Use HTTP GET to check for dvStatus.status=valid for each domain in your certificate.

Option #3: deploy tokens on your web server to complete the challenge:

  1. Each domain will have a unique dvStatus JSON object returned from the HTTP GET operation. Take note of the dvStatus.fullPath and dvStatus.responseBody for each domain that needs to be validated.

    fullPath example:

    http://www.example.com/.well-known/acme-challenge/0uYE2IaeO2qK8ZPsR5TJO_hFBNXtmweZvxwOCVZrzFF&sa=D&usg=AFQjCNHrYAu23Z1xYW5ReD13JYb3QnPcbQ0uYE2IaeO2qK8ZPsR5TJO_hFBNXtmweZvxwOCVZrzFF
    

    responseBody example:

    ayJqd2siOnsia3R5IjoiUlNBIiwibiI6 ... LQwlchRqm-_nJoGUQ0zVbxIcHjGA4S3F
    
  2. Configure your web server to serve the specified responseBody for HTTP GET requests at the fullPath URL. Do this for each domain that needs to be validated.

  3. Akamai will periodically poll the fullPath URL to confirm that it is serving the challenge token. When Akamai recognizes that the challenge token is being served, Akamai will programmatically instruct the CA to perform validation of the domain. This process is expected to take several minutes but less than one hour.

  4. Use HTTP GET to check for dvStatus.status=valid for each domain in your certificate.

    Check that the CA has validated the domain:

    $ python egcurl -k -X GET 'HOST/config-secure-provisioning-service/v1/sps-requests/12345/?contractId=11754&groupId=1001'
    
    {
       "dvStatus" : [
      {
         "domainName" : "www.example.com",
         "expiresTimestamp" : "2016-07-21T16:11:02Z",
         "fullPath" : "[http://www.sps-waa-san-le-cname-dcv-11.webexp-ipqa1.com/.well-known/acme-challenge/xaUZ3KKOhYhuUlcWvRB5-H9qHe8Hyyi0aSmSeDGUnSc](http://www.sps-waa-san-le-cname-dcv-11.webexp-ipqa1.com/.well-known/acme-challenge/xaUZ3KKOhYhuUlcWvRB5-H9qHe8Hyyi0aSmSeDGUnSc&sa=D&usg=AFQjCNHS-Xhs61wpqvn94agpeMt-JdahHg)",
         "redirectFullPath" : "http://dcv.akamai.com/.well-known/acme-challenge/www.example.com/xaUZ3KKOhYhuUlcWvRB5-H9qHe8Hyyi0aSmSeDGUnSc",
         "requestTimestamp" : "2015-09-23T22:33:25Z",
         "responseBody" : "eyJqd2siOnsia3R5IjoiUlNBIiwibiI6 ... m0RPsWDkjapoH7WyJ2KjiGTm4PUrv-qA",
         "status" : "Valid",
         "token" : "xaUZ3KKOhYhuUlcWvRB5-H9qHe8Hyyi0aSmSeDGUnSc",
         "validatedTimestamp" : "2015-09-25T16:11:03Z"
      }
       ],
       "jobId" : 67890,
       "lastStatusChange" : "2015-09-25T19:49:19Z",
       "resourceUrl" : "/config-secure-provisioning-service/v1/sps-requests/12345",
       "spsId" : 12345,
       "status" : "SPS Request Complete",
       "workflowProgress" : "All of your requested changes are complete."
    }
    

Add a Domain Name to a SAN Certificate

Since this use case is for an existing SAN certificate, you have to include the jobId parameter. This parameter is the jobId received from either a finished SPS request, or from CPS. Using this parameter allows you to add new alternative hostnames to an existing certificate.

Run the following POST operation:

$ python egcurl -X POST -d 'HOST/config-secure-provisioning-service/v1/sps-requests/?contractId=11754&groupId=1001' --data @formparams

with a URL-encoded file called formparams which is for modifications to an existing SAN certificate:

cnameHostname=www.example.cname-hostname300.com&jobId=10110&&createType=modSan&add.sans=www.example.net&add.sans=www.new-example.net&product=alta

NOTE: As this is an existing SAN certificate, the add.sans parameter is included. This use case assumes that www.example.com and www.new-example.com, which are in the create SAN certificate example, were already included in the existing SAN certificate.

Response body with a 202 HTTP status:

{
   "Results" : {
      "data" : [
         {
            "code" : null,
            "data" : null,
            "message" : null,
            "results" : {
               "enrollmentId" : 54321,
               "jobID" : 67890,
               "type" : "SUCCESS"
            },
            "text" : null
         }
      ],
      "size" : 1
   },
   "resourceLocation" : "/config-secure-provisioning-service/v1/sps-requests/12345",
   "spsId" : 12345
}

Verify that the SPS request has completed successfully:

$ python egcurl -k -X GET 'HOST/config-secure-provisioning-service/v1/sps-requests/12345/?contractId=11754&groupId=1001'
{
   "requestList" : [
      {
         "enrollmentId" : 54321,
         "jobId" : 67890,
         "lastStatusChange" : "2015-10-13T19:31:35Z",
         "resourceUrl" : "/config-secure-provisioning-service/v1/sps-requests/12345",
         "spsId" : 12345,
         "status" : "SPS Request Complete",
         "workflowProgress" : "All of your requested changes are complete."
      }
   ]
}

Retrieve Information About the Request

Because SPS is an asynchronous API, you must check that your request has completed by performing an HTTP GET. Furthermore, information such as enrollmentId returned by the HTTP GET can be used in conjunction with the CPS API.

SPS cannot perform the following advanced operations on certificates including the following:

  • Cancelling an order

  • Editing a submitted SAN order

  • Removing SANs

You can use the CPS API to perform the above operations. In order to use CPS API to perform advanced operations on certificates created with the SPS API, you must retrieve the enrollmentId from SPS.

$ python egcurl -k -X GET 'HOST/config-secure-provisioning-service/v1/sps-requests/12345/?contractId=11754&groupId=1001'
{
   "requestList" : [
      {
         "enrollmentId" : 54321,
         "jobId" : 67890,
         "lastStatusChange" : "2015-10-13T19:31:35Z",
         "resourceUrl" : "/config-secure-provisioning-service/v1/sps-requests/12345",
         "spsId" : 12345,
         "status" : "SPS Request Complete",
         "workflowProgress" : "All of your requested changes are complete."
      }
   ]
}

Create a Secure Edge Hostname with an Existing Certificate

This use case is an example of creating an SPS request when you have one of the following:

  • a certificate

  • a jobId or an enrollmentId from the POST operation used in the other use cases or from CPS.

Run the following POST operation:

$ python egcurl -X POST -d 'HOST/config-secure-provisioning-service/v1/secure-edge-hosts/?contractId=11754&groupId=1001' --data @formparams

with a URL-encoded file called formparams that includes the following, which is for modifications to an existing SAN certificate:

cnameHostname=www.example.cname-hostname300.com&enrollmentId=2112&ipVersion=ipv4&product=alta
{
   "resourceLocation" : "/config-secure-provisioning-service/v1/sps-requests/24660",
   "spsId" : 24660
}

NOTE: In this use case, you use the enrollmentId parameter. The enrollmentId is returned with a completed CPS request, and includes the slot and certificate information needed to create a new edge hostname. While it is not necessary to include both a jobId and a enrollmentId, if you enter both parameters the enrollmentId overrides the jobId.

Verify that the SPS request has completed successfully:

$ python egcurl -k -X GET 'HOST/config-secure-provisioning-service/v1/sps-requests/12345/?contractId=11754&groupId=1001'

Last modified: 12/12/2016