Learn more:

• Certificate Provisioning System API

Overview

The Secure Provisioning Service (SPS) provides a convenient mechanism to provision certificates and secure edge hostnames. You can either use this API by itself, or you can use it in conjunction with the Certificate Provisioning System API (CPS).

SPS provides Akamai’s only automated mechanism to provision secure edge hostnames. In addition, SPS can provision the most common certificate types and can add domain names to a SAN certificate. To perform advanced operations with certificates, use the CPS API. The CPS API is Akamai’s comprehensive toolbox for creating and modifying certificates. Since CPS and SPS both use enrollmentId to identify certificates, you can use the enrollmentId returned by one system as input on requests to the other system.

SPS is an asynchronous API. Once you successfully submit a request, the API returns an ID which you can use to track the status of the request as it creates a certificate and secure edge hostname.

The timeline for certificate validation depends on many factors, including the number of domains and the responsiveness of the organization. Akamai now supports domain validation (DV) of certificates in addition to organization validation (OV). Akamai’s experience with OV certificates is that while the validation process can take several days, it can extend to much longer periods.

NOTE: SPS no longer supports Geotrust or Cybertrust certificates. Symantec is now the exclusive provider of organizational validation (OV) certificates. For more information, see Akamai Community.

Who should use this API

The SPS API allows developers and architects to create certificates and secure edge hostnames to apply to properties. To use this API effectively, you must be familiar with the process for obtaining and managing certificates. This document assumes readers are familiar with the terminology and concepts specific to Akamai Control Center. Before you can access the SPS API, you need to make sure SPS has been added to your contract.

Developers using this API should be familiar with:

• SSL certificates.

• CAs.

• How Akamai obtains certificates on the requestor’s behalf, which includes the generation of public/private key pairs and CSRs (certificate signing requests).

• DNS.

• Edge Hostnames.

If you have questions about these concepts, contact your Akamai account representative.

API conventions

The SPS API follows ISO 8601, the international standard for the representation of date and time values. The format is as follows. The T appears literally in the string to indicate the beginning of the time element:

2014-08-12T18:57:07Z

Get started

To get started with this API:

• Contact your Akamai representative to enable SPS for your account.

• Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

• To enable this API, choose the API service named SPS Requests, and set the access level to READ-WRITE.

• Get help from the Akamai developer community and provide feedback. You can also contact your Akamai representative for support.

Concepts

When using this API, you should be familiar with the following concepts

• Group IDs and Contract IDs

• Secure Edge Hostnames

• Certificates

• SHA

• SNI

• Domain Validation

About group and contract IDs

When using this API, your level of access depends on the groups and contracts for which your Control Center username is associated. If your username is not associated with the groupId and contractId you selected, then the request fails.

To understand contracts and groups, you need to understand how accounts work at Akamai. Akamai customers access all their services via an account key. While administrators may have access to more than one account, in general they provision all their web assets under a single account. Within an account, there are contracts and groups:

• contracts: Each account features one or more contracts, each of which has a fixed term of service during which specified Akamai products and optional modules are active.

• groups: Each account features a hierarchy of groups, which control access to properties and help consolidate reporting functions, typically according to your firm’s own organizational hierarchy.

When using any of the POST operations available for this API, you must include the groupId and contractId in the query parameter, in order to associate the appropriate group and contract with the request. Similarly, for the GET operations, you must specify the groupId and contractId to determine exactly which SPS requests you want to access.

About edge hostnames

A secure edge hostname is a host for each of your sites or applications that resolves to an Akamai domain. 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.

About certificates

You can use SPS to create the following types of secure sockets layer (SSL) certificates.

• Single certificate: Covers a single, specific domain.

• *Wildcard certificate: Allows the use of wildcards to cover a single level of a subdomain with a single certificate.

• Subject Alternative Name (SAN) certificate: Allows you to cover multiple hostnames with a single certificate.

You can also use SPS to add domain names to an existing SAN certificate.

NOTE: All certificate options support organization validation (OV), where the certificate authority (CA) verifies that the organization applying for the certificate has rights to the specific domain. You can use SAN certificates either with organization validation (OV) or Domain Validation (DV).

About SHA

One piece of certificate information that you must specify is the SHA (Secure Hash Algorithm) function. SPS defaults to SHA–256, and we recommend using this default. You can optionally specify SHA–1. This is only for the certificate, not for cipher suites.

About SNI

You also must decide if you want to create a certificate that uses server name indication (SNI). SNI is an extension of the transport layer security (TLS) networking protocol. It allows a server to present multiple certificates on the same IP address and TCP port number and therefore allows multiple secure (HTTPS) websites, or any other Service over TLS, to be served off the same IP address without requiring all those sites to use the same certificate. When making a TLS connection the client requests a digital certificate from the web server. Once the server sends the certificate, the client examines it and compares the name it was trying to connect to with the name or names included in the certificate. If a match occurs the connection proceeds as normal. If a match is not found you may be warned of the discrepancy and the connection may abort.

About domain validation

Domain validation (DV) is a level of validation where the CA only validates that you have control of the domain listed in the certificate. Akamai presently supports domain validation only with the Let’s Encrypt certificate authority, and only for SAN certificates.

When using certificates with domain validation, you prove that you have control over each of the domains listed in the certificate by serving a token at a specific path on each domain. The certificate authority performs an HTTP GET on a specific URL for each domain, and marks the domain as validated if it receives the response it expects.

There are three options to serve the token to complete the DV challenge:

• Explicitly configure a redirect to dcv.akamai.com

• Use automated challenge completion

• Serve the challenge token from your web server

Explicitly configure a redirect to dcv.akamai.com

You can explicitly configure a redirect to dcv.akamai.com if:

• You are creating a new certificate, automated validation is not an option. In this case you should configure your web server to redirect the challenge path to Akamai. After you configure the redirection, the token is served by Akamai.

• If you want to add a new name to an existing certificate and you have not CNAMEd the new domain to the edge host server to which you want to add the domain, automated validation is not an option. In this case you should configure your web server to redirect the challenge path to Akamai

• Take note of the dvStatus.fullPath and dvStatus.redirectPath for each domain that must be validated. Configure your web server so that requests to fullPath are redirected to redirectPath. Some examples of this include:

  • For a fullPath: http://www.example.com/.well-known/acmechallenge/0uYE2IaeO2qK8ZPsR5TJO_hFBNXtmweZvxwOCVZrzFF

  • For a redirectFullPath: http://dcv.akamai.com/.well-known/acme-challenge/www.domain-to-be-validated.com/0uYE2IaeO2qK8ZPsR5TJO_hFBNXtmweZvxwOCVZrzFF

Use automated challenge completion

You can use automated challenge completion:

• If you are adding a new name to an existing certificate and you have CNAMEd the new domain to the edge host server to which the domain is being added, you don’t have to do anything else. Akamai services the response automatically.

• If you want to validate domains on an existing certificate due to ordinary maintenance, and you have CNAMEd your domains to the CN/edgehostnames on the certificate, you don’t have to do anything else. Akamai serves the response automatically.

Serve the challenge token from your web server

You always have the option to download the challenge token and serve it at the specified path on your own web server, if this is practical for your situation.

When Let’s Encrypt is awaiting completion of the challenges, the status of your enrollment changes to Pending while CPS processes the request, and then Awaiting User, after which CPS cannot continue until you make validation changes to your domain. After each challenge completes, the corresponding dvStatus.status changes to Valid. Once all challenge URLs validate, the certificate issues and deploys to the Akamai network, and the status of the SPS request becomes the literal value of SPS Request Complete. A DV certificate expires in one year.

Resources

The Secure Provisioning Service (SPS), or Secure Domain Provisioning API, provides a method for provisioning certificates and secure Edge Hostnames.

API summary

Create a request

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

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

List SPS requests

{
    "requestList": [
        {
            "status": "SPS Request Complete",
            "spsId": 7890,
            "jobId": 10110,
            "enrollmentId": 54321,
            "workflowProgress": "All of your requested changes are complete.",
            "resourceUrl": "/sps/v1/sps_request/7890",
            "lastStatusChange": "2014-07-08T16:27:06Z",
            "parameters": [
                {
                    "name": "cnameHostname",
                    "value": "www.example.com"
                },
                {
                    "name": "createType",
                    "value": "single"
                },
                {
                    "name": "csr.cn",
                    "value": "www.example.akamai.com"
                },
                {
                    "name": "csr.c",
                    "value": "US"
                },
                {
                    "name": "csr.st",
                    "value": "MA"
                },
                {
                    "name": "csr.l",
                    "value": "Boston"
                },
                {
                    "name": "csr.o",
                    "value": "Akamai"
                },
                {
                    "name": "csr.ou",
                    "value": "Engineering"
                },
                {
                    "name": "organization-information.organization-name",
                    "value": "Any Company, Inc."
                },
                {
                    "name": "organization-information.address-line-one",
                    "value": "1 Main Street"
                },
                {
                    "name": "organization-information.city",
                    "value": "Anytown"
                },
                {
                    "name": "organization-information.region",
                    "value": "MA"
                },
                {
                    "name": "organization-information.postal-code",
                    "value": "02125"
                },
                {
                    "name": "organization-information.country",
                    "value": "US"
                },
                {
                    "name": "organization-information.phone",
                    "value": "617-999-9999"
                },
                {
                    "name": "admin-contact.first-name",
                    "value": "John"
                },
                {
                    "name": "admin-contact.last-name",
                    "value": "Doe"
                },
                {
                    "name": "admin-contact.phone",
                    "value": "617-999-9999"
                },
                {
                    "name": "admin-contact.email",
                    "value": "jdoe@AnyCompany.com"
                },
                {
                    "name": "technical-contact.first-name",
                    "value": "Jane"
                },
                {
                    "name": "technical-contact.last-name",
                    "value": "Smith"
                },
                {
                    "name": "technical-contact.phone",
                    "value": "617-222-2222"
                },
                {
                    "name": "technical-contact.email",
                    "value": "jsmith@Akamai.com"
                },
                {
                    "name": "slot-deployment.klass",
                    "value": "esslType"
                },
                {
                    "name": "issuer",
                    "value": "geotrust"
                },
                {
                    "name": "contractId",
                    "value": "1-contract"
                },
                {
                    "name": "groupId",
                    "value": "987"
                },
                {
                    "name": "ipVersion",
                    "value": "ipv4"
                },
                {
                    "name": "product",
                    "value": "alta"
                }
            ]
        },
        {
            "status": "SPS Request Complete",
            "spsId": 2341,
            "jobId": 67541,
            "enrollmentId": 89765,
            "workflowProgress": "All of your requested changes are complete.",
            "resourceUrl": "/sps/v1/sps_request/2341",
            "lastStatusChange": "2014-07-08T16:27:06Z",
            "parameters": [
                {
                    "name": "cnameHostname",
                    "value": "www.example2.com"
                },
                {
                    "name": "createType",
                    "value": "single"
                },
                {
                    "name": "csr.cn",
                    "value": "www.example2.akamai.com"
                },
                {
                    "name": "csr.c",
                    "value": "US"
                },
                {
                    "name": "csr.st",
                    "value": "MA"
                },
                {
                    "name": "csr.l",
                    "value": "Boston"
                },
                {
                    "name": "csr.o",
                    "value": "Akamai"
                },
                {
                    "name": "csr.ou",
                    "value": "Engineering"
                },
                {
                    "name": "organization-information.organization-name",
                    "value": "Any Company, Inc."
                },
                {
                    "name": "organization-information.address-line-one",
                    "value": "1 Main Street"
                },
                {
                    "name": "organization-information.city",
                    "value": "Anytown"
                },
                {
                    "name": "organization-information.region",
                    "value": "MA"
                },
                {
                    "name": "organization-information.postal-code",
                    "value": "02125"
                },
                {
                    "name": "organization-information.country",
                    "value": "US"
                },
                {
                    "name": "organization-information.phone",
                    "value": "617-999-9999"
                },
                {
                    "name": "admin-contact.first-name",
                    "value": "John"
                },
                {
                    "name": "admin-contact.last-name",
                    "value": "Doe"
                },
                {
                    "name": "admin-contact.phone",
                    "value": "617-999-9999"
                },
                {
                    "name": "admin-contact.email",
                    "value": "jdoe@AnyCompany.com"
                },
                {
                    "name": "technical-contact.first-name",
                    "value": "Jane"
                },
                {
                    "name": "technical-contact.last-name",
                    "value": "Smith"
                },
                {
                    "name": "technical-contact.phone",
                    "value": "617-222-2222"
                },
                {
                    "name": "technical-contact.email",
                    "value": "jsmith@Akamai.com"
                },
                {
                    "name": "slot-deployment.klass",
                    "value": "esslType"
                },
                {
                    "name": "issuer",
                    "value": "geotrust"
                },
                {
                    "name": "contractId",
                    "value": "1-contract"
                },
                {
                    "name": "groupId",
                    "value": "987"
                },
                {
                    "name": "ipVersion",
                    "value": "ipv4"
                },
                {
                    "name": "product",
                    "value": "alta"
                }
            ]
        }
    ]
}

Get an SPS request

View information about an existing SPS request.

{
    "requestList": [
        {
            "status": "SPS Request Complete",
            "spsId": 7890,
            "jobId": 10110,
            "enrollmentId": 54321,
            "workflowProgress": "All of your requested changes are complete.",
            "resourceUrl": "/sps/v1/sps_request/7890",
            "lastStatusChange": "2014-07-08T16:27:06Z"
        }
    ]
}

Create a secure edge hostname

Create a secure edge hostname from an existing subscriptionId or jobId.

cnameHostname=www.sehncreate.cname-hostname300.com&jobId=10110

{
    "spsId": 24660,
    "resourceLocation": "/config-secure-provisioning-service/v1/sps-requests/24660"
}

Usage

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

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 your API’s BASE_URL.

NOTE: The examples in these use cases are in egcurl, which is a Python script used with curl for authorizing Akamai API clients.

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

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 GET on 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'

Data

This section shows you the data model for the Secure Provisioning Service (SPS) API.

SPS requests

The following describes the form parameters used to get information about SPS requests, and JSON members included in responses.

This is the format of the URL:

/config-secure-provisioning-service/v1/sps-request/{spsId}{?contractId,groupId,after,information}

The following table shows the URL parameter and query parameters required for these operations:

In addition, the following optional query parameters are available for these GET operations:

Request form parameters

The following provides details on form parameters included in requests. Unless you are modifying an existing Subject Alternative Name (SAN) certificate, all parameters are required unless otherwise noted.

NOTE: “Organization” refers to the entity on whose behalf the certificate request is being created.

Read-only form parameters returned on a GET

The following provides details on read-only parameters returned with each GET operation.

SpsRequest response

The following JSON shows a sample SPS GET response. It includes an optional dvStatus object available when you use a domain validation certificate. In addition, the parameters reflect back the set of form parameters used in the initial request when you set the information URL query parameter to true:

{
   "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."
         "parameters": [
             {
                 "name": "cnameHostname",
                 "value": "www.example.com"
             },
             {
                 "name": "csr.cn",
                 "value": "www.example.akamai.com"
             }
         ]
      }
   ]
}

SpsRequest.requestList[]  

When you have multiple GETs, each SpsRequest is available within the response object’s requestList array member. The following encapsulates basic information about SPS requests:

SpsRequest POST Responses

Responses to SPS Request POSTs use a different data structure than for GETs, shown below:

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

SpsRequest POST Response members

The outer object is a contextual wrapper whose Results member contains the results from the CPS API.

Response members

The following example shows the sort of JSON included in successful responses:

{
   "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."
      }
   ]
}

The following provides details on each JSON member:

Secure edge hostnames

When creating an SPS request using an existing certificate, a URL-encoded form is passed with all the information needed to provision both a certificate and a secure edge hostname.

In the case of secure-edge-host operation, the secure edge hostname is created from a completed CPS job that is valid for the contract and group you entered as part of the request. This CPS job has a certificate associated with it. For this operation, you must specify one of the following parameters:

• jobId: The job-specific ID received from either a completed SPS request, or from CPS.

• enrollmentId: This parameter references the enrollment for the active certificate in CPS, and includes information needed to create a new edge hostname. The CPS UI or the CPS API returns the enrollmentId and it is what you reference to the CPS API to alter the certificate.

If you include both a jobId and a enrollmentId, the enrollmentId will override the jobId.

NOTE: You can check the status with the GET operations that use the sps-requests endpoint.

Request form parameters

The following shows the format of the request URL:

/config-secure-provisioning-service/v1/secure-edge-hosts/{?contractId,groupId}

Here is a sample request:

POST http://localhost:8080/config-secure-provisioning-service/v1/secure-edge-hosts/?contractId=11754&groupId=1001 --data @formparams

In this example, a URL-encoded formparams file specifies a new single certificate, and includes the following information:

cnameHostname=www.example.cname-hostname300.com&enrollmentId=2112&product=alta

The following lists form parameters included in requests:

The spsId parameter is the ID number of the specific SPS request to get information on.

Response members

The following shows a typical response to a request for a new secure edge hostname:

[
   {
      "resourceLocation" : "/config-secure-provisioning-service/v1/sps-requests/12345",
      "spsId" : 12345
   }
]

The following provides details on the JSON’s members:

Errors

This section provides information on the SPS API’s common JSON format for error responses, and details the full range of HTTP response codes.

Error responses

When a non 2XX HTTPS status code is returned, a JSON error, like the following, is also returned:

HTTP/1.1 400

Content-Type: application/json

Reply Body:

{
   "Errors" : {
      "invalidItems" : [
         {
            "field" : "csr.cn",
            "spsId" : 2430,
            "validation" : "Invalid parameter input",
            "validationDescription" : "The requested CN www.example.com is currently active. Please call your akamai contact for further assistance."
         }
      ]
   },
   "Results" : "Errors"
}

HTTP status codes

The API produces the following range of response codes:

Last modified: 12/12/2016