Secure Provisioning Service API v1

Securely provision certificates and edge hostnames.

Learn more:


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 the Luna 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

Getting started

To get started with this API:

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

  • Review Get Started for available tools.

  • Review the Authorize Your Client section to create your Akamai API access credentials and authorizations, making sure you enable read/write access for this API grant.

  • 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 Luna 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

Operation Method Endpoint
Requests
Create a Request POST /config-secure-provisioning-service/v1/sps-requests{?contractId,groupId,after,information}
List SPS Requests GET /config-secure-provisioning-service/v1/sps-requests{?contractId,groupId,after,information}
Get an SPS Request GET /config-secure-provisioning-service/v1/sps-request/{spsId}{?contractId,groupId,after,information}
Secure Edge Hostnames
Create a Secure Edge Hostname POST /config-secure-provisioning-service/v1/secure-edge-hosts{?contractId,groupId}

Create a request

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

Example: /config-secure-provisioning-service/v1/sps-requests?contractId=11754&groupId=1001&after=2014–07–08T16%3A27%3A06Z&information=false

Content-Type: application/x-www-form-urlencoded

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

Parameter Type Sample Description
Required
contractId Number 11754 For POST requests, the ID of the contract associated with the new policy. To retrieve the contractId you need, see the Property Manager API.
groupId Number 1001 For POST requests, the ID of the group associated with the new policy. To retrieve the groupId you need, see the Property Manager API.
Optional
after String 2014-07-08T16:27:06Z If specified for GET requests, returns only the SPS requests created after the date entered. Enter the combined date and time in UTC, using the ISO 8601 date format: yyyy-MM-dd'T'HH:mm:ss'Z'.
information Boolean false If specified for GET requests, returns parameters posted with the SPS request resource.

Status 202 application/json

Response:

{
    "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

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

Example: /config-secure-provisioning-service/v1/sps-requests?contractId=11754&groupId=1001&after=2014–07–08T16%3A27%3A06Z&information=false

Parameter Type Sample Description
Required
contractId Number 11754 For POST requests, the ID of the contract associated with the new policy. To retrieve the contractId you need, see the Property Manager API.
groupId Number 1001 For POST requests, the ID of the group associated with the new policy. To retrieve the groupId you need, see the Property Manager API.
Optional
after String 2014-07-08T16:27:06Z If specified for GET requests, returns only the SPS requests created after the date entered. Enter the combined date and time in UTC, using the ISO 8601 date format: yyyy-MM-dd'T'HH:mm:ss'Z'.
information Boolean false If specified for GET requests, returns parameters posted with the SPS request resource.

Status 200 application/json

Response:

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

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

Example: /config-secure-provisioning-service/v1/sps-request/1406?contractId=11754&groupId=1001&after=2014–07–08T16%3A27%3A06Z&information=false

Parameter Type Sample Description
Required
contractId Number 11754 The ID of the contract associated with the new policy. To retrieve the contractId you need, see the Property Manager API.
groupId Number 1001 The ID of the group associated with the new policy. To retrieve the groupId you need, see the Property Manager API.
spsId Number 1406 The ID of a completed SPS request.
Optional
after Date 2014-07-08T16:27:06Z If specified, returns only the SPS requests created after the date entered. Enter the combined date and time in UTC, using the ISO 8601 date format: yyyy-MM-dd'T'HH:mm:ss'Z'.
information Boolean false If specified, will return parameters posted with the SPS request resource.

Status 200 application/json

Response:

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

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

Example: /config-secure-provisioning-service/v1/secure-edge-hosts?contractId=11754&groupId=1001

Content-Type: application/x-www-form-urlencoded

Request:

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

Parameter Type Sample Description
Required
contractId Number 11754 The ID of the contract associated with the new policy. To retrieve the contractId you need, see the Property Manager API.
groupId Number 1001 The ID of the group associated with the new policy. To retrieve the groupId you need, see the Property Manager API.

Status 202 application/json

Response:

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

Usage

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 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. 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 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:

Operation Required Parameters
Get all SPS requests for a contract and group contractId, groupId
Get a specific SPS request contractId, groupId, spsId

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

Parameter Description
Optional
after If specified, returns only the SPS requests created after the date entered. Enter the combined date and time in UTC, using the ISO 8601 date format: yyyy-MM-dd'T'HH:mm:ss'Z'. SPS ignores this parameter if you specify an spsId in the GET. If you use this parameter, you want to see all the requests after a certain date, but if you specify the spsId, you only get the data for the one request, and SPS ignores the after parameter.
information If set to true, returns parameters posted with the SPS request resource.

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.

Parameter Type Applies to Description
Required
add.sans String ModSan For modSan only. The additional alternative hostnames for modifying an existing SAN certificate. You can include this parameter multiple times.
admin-contact.email String Single, Wildcard, SAN The email address of the administrative contact for this certificate.
admin-contact.first-name String Single, Wildcard, SAN The first name of the administrative contact for this certificate.
admin-contact.last-name String Single, Wildcard, SAN The last name of the administrative contact for this certificate.
admin-contact.phone String Single, Wildcard, SAN The phone number of the administrative contact for this certificate.
cnameHostname String Single, Wildcard, SAN, ModSan The new, secure edge hostname.
createType Enumeration Single, Wildcard, SAN, ModSan The SPS request type. Valid options are: single to create a new single certificate, san to create a new SAN certificate, wildcard to create a new wildcard certificate,and modSan to modify an existing SAN certificate.
csr.cn String Single, Wildcard, SAN The Common Name for the certificate, which is the fully qualified domain name (FQDN) of your host (such as www.example.com).
csr.ou String Single, Wildcard, SAN The organizational unit (such as division or department) requesting the certificate.
csr.sans String SAN For SAN only. The alternative hostnames for a SAN certificate. This parameter is optional and you can include this parameter multiple times.
jobId Number modSan For modSan only. This parameter is the job-specific Id received from either a finished SPS request, or from CPS.
organization-information.address-line-one String Single, Wildcard, SAN The first line of the organization’s address.
organization-information.city String Single, Wildcard, SAN The city in which the organization resides. This parameter, required in POSTs, populates the value of csr.l, which it returns in a GET.
organization-information.country String Single, Wildcard, SAN The two-character ISO–3166 code for the country where your organization is located. This parameter, required in POSTs, populates the value of csr.c, which it returns in a GET.
organization-information.organization-name String Single, Wildcard, SAN The name of the organization on whose behalf the certificate request is being created. This parameter, required in POSTs, populates the value of csr.o, which it returns in a GET.
organization-information.phone String Single, Wildcard, SAN The phone number of the organization.
organization-information.postal-code String Single, Wildcard, SAN The postal code for the organization.
organization-information.region String Single, Wildcard, SAN Represents the state or province the organization is in. This parameter, required in POSTs, populates the value of csr.st, which it returns in a GET.
product Enumeration Single, Wildcard, SAN, ModSan If multiple products are on the contract, specify the product to use when creating the edge hostname map. Valid products include Alta (alta), Ion Standard (ion_standard), Ion Media Advanced (ion_media), Ion Premier (ion_premier), WAA (waa), Dynamic Site Delivery (dsd), Integrated Cloud Accelerator (ica), Wholesale Delivery (wsd), and Dynamic Site Acceleration (dsa). This is optional if the contract only supports one product.
Optional
certificate-request.signature-algorithm Enumeration Single, Wildcard, SAN This defaults to use SHA-256 if you do not specify this parameter. You can also specify SHA-1. We recommend using the default value. The SHA (Secure Hash Algorithm) function helps protect the integrity of a certificate and prevent forgery.
ipVersion Enumeration Single, Wildcard, SAN, ModSan The IP version being used for the edge hostname you are creating. IPv4 (ipv4) is selected by default. You can also select dual-stacked (ipv4_ipv6). However, IPv6 is not supported.
issuer String Single, Wildcard, SAN The issuer of the certificate. The following are the defaults, which are based on the createType: single defaults to Symantec; wildcard defaults to Symantec; san defaults to Symantec; modSan defaults to the certificate issuer listed for the existing SAN certificate. You cannot change the issuer. For more information about how validation type works with the default issuer, see the Resources section.
organization-information.address-line-two String Single, Wildcard, SAN Defines the second line of the organization’s address.
slot-deployment.klass Enumeration Single, Wildcard, SAN, ModSan Defines the certificate network deployment type. (The default for this parameter is esslType.) chinaType is also available for this parameter.
subscription-sni-only Boolean Single, Wildcard, SAN The default is false. Specify true if you want to create a certificate that uses server name indication (SNI). This allows you 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. After you use this parameter to create an SAN certificate with SNI, if you choose to modify your SAN certificate, you cannot modify the SNI status of the the certificate. You can only use this parameter for a wildcard or a wildcard SAN certificate.
validationType Enumeration Single, Wildcard, SAN Either ov for organization validation or dv for domain validation.

Read-only form parameters returned on a GET

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

Parameter Type Required Description
csr.o String The name of the organization on whose behalf the certificate request is being created. This parameter is read-only. SPS returns it in a GET.
csr.l String The city in which the organization resides.
csr.st String Represents the state or province the organization is in.
csr.c String The two-character ISO–3166 code for the country where your organization is located.
technical-contact.first-name String The first name of the technical contact for this certificate. SPS retrieves this information from the database and returns in a GET.
technical-contact.last-name String The last name of the technical contact for this certificate. SPS retrieves this information from the database and returns in a GET.
technical-contact.phone String The first name of the technical contact for this certificate. SPS retrieves this information from the database and returns in a GET.
technical-contact.email String The email address of the technical contact for this certificate. SPS retrieves this information from the database and returns in a GET.
default_validation_type_used String This parameter is a read-only, debug parameter.
default_issuer_used String This parameter is a read-only, debug parameter for internal use only.

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:

Member Type Required Description
dvStatus SpsRequest.requestList.dvStatus[] When you use a domain validated certificate, this encapsulates information about the certificate as detailed below.
enrollmentId Number 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, which you reference to the CPS API to alter the certificate.
jobId Number The job ID from a completed SPS or CPS request.
lastStatusChange String The last time the status of the SPS request changed.
parameters SpsRequest.requestList.parameters[] When the request’s information query parameter is true, this object described below reflects the initial request’s set of form parameters.
resourceUrl String The URL to use to check on the status of an SPS request.
spsId Number The integer ID for a completed SPS request.
status Enumeration Displays one of the following statuses: Pending: Waiting for CPS to process a request; Awaiting user: Waiting for you to manually push the challenge file; Pending RA: Waiting for Let’s Encrypt to validate the certificate; Valid: Let’s Encrypt validated the certificate; Invalid: Let’s Encrypt did not validate the certificate; Error: An error occurred.
workflowProgress Enumeration Indicates the stage of the process your request is in while it is in CPS, and returns any of the following messages indicating workflow progress: The system is waiting to begin processing your request. The system is preparing your certificate request. The system is waiting to receive your certificate from the CA. Wait for user to acknowledge certificate post-verification warnings. The network is updating with your changes. All of your requested changes are complete.
SpsRequest.requestList.dvStatus[]: This object describes the information you need for each domain during domain validation.
domainName String The domain name you want to validate. Example: www.example.com
errorMessage String Captures a detailed error message. This is only valid when the status is set to Error.
expiresTimestamp String Expiration timestamps in ISO 8601 format (e.g. 2014-08-12T18:57:07Z). This is only valid when the status is set to Valid. Example: 2015-08-27T17:35:57Z
fullPath String The full URL to the challenge file. Example: http://www.example.com/.well-known/acme-challenge/0uYE2IaeO2qK8ZPsR5TJO_hFBNXtmweZvxwOCVZrzFF
redirectFullPath String Contains the full path that can be installed for redirect. Example: http://dcv.akamai.com/.well-known/acme-challenge/www.domain-to-be-validated.com/0uYE2IaeO2qK8ZPsR5TJO_hFBNXtmweZvxwOCVZrzFF
requestTimestamp String Request timestamps in ISO 8601 format. CPS timestamps it when it makes the first request to Let’s Encrypt for the domain validation.
responseBody String Contains the token in a challenge file located at the full path. Example: eyJqd2siOnsia3R5IjoiUlNBIiwibiI6...
status Enumeration Displays one of the following statuses: Pending: Waiting for CPS to process a request; Awaiting user: Waiting for you to manually push the challenge file; Pending RA: Waiting for Let’s Encrypt to validate the certificate; Valid: Let’s Encrypt validated the certificate; Invalid: Let’s Encrypt did not validate the certificate; Error: An error occurred.
token String The token value.
validatedTimestamp String Validated timestamp in ISO 8601 format (e.g. 2014-08-12T18:57:07Z). CPS timestamps it when it receives the information that Let’s Encrypt validated the domain. Example: 2015-08-27T17:35:57Z
SpsRequest.requestList.parameters[]: Objects within the parameters array reflect the initial request’s set of form parameters. These objects only appear in responses when the request’s information URL query parameter is true.
name String The name of the initial request’s form parameters.
value String The value that corresponds to the form parameter’s name.

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.

Member Type Required Description
spsId Number The integer ID for a completed SPS request.
resourceLocation String This member corresponds to resourceUrl.
Results POST.Results An object that encapsulates the results from the CPS API. This member is not present when creating new secure edge hostnames.
POST.Results
data POST.Results.data[] An array of objects that contain results from the CPS API.
size Number Describes the length of the array.
POST.Results.data[]
code null deprecated
data null deprecated
message null deprecated
results POST.Results.data.results This inner results object holds the IDs relevant to certificate management.
text null deprecated
POST.Results.data.results
jobId Number The job ID from a SPS or CPS request.
enrollmentId Number References the enrollment for the active certificate in CPS, and includes information needed to create a new edge hostname. The CPS UI, which is part of Luna Control center, or the CPS API returns the enrollmentId, which you reference to the CPS API to alter the certificate. The CPS UI or the CPS API returns the enrollmentId, which you reference to the CPS API to alter the certificate.
type Enumeration Either SUCCESS or VALIDATION_FAILURE of the POST.

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:

Member Type Required Description
enrollmentId Number 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.
jobId Number The job ID from a completed SPS or CPS request.
resourceUrl String The URL to use to check on the status of an SPS request.
spsId Number The integer ID for a completed SPS request.
type Enumeration Either SUCCESS or VALIDATION_FAILURE.
workflowProgress Enumeration Indicates the stage of the process your request is in while it is in CPS, and returns any of the following messages indicating workflow progress: The system is waiting to begin processing your request. The system is preparing your certificate request. The system is waiting to receive your certificate from the CA. Wait for user to acknowledge certificate post-verification warnings. The network is updating with your changes. All of your requested changes are complete.

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:

Parameter Type Required Description
cnameHostname String Defines the edge hostname.
enrollmentId Number 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, which you reference to the CPS API to alter the certificate.
ipVersion Enumeration Defines The IP version being used for the edge hostname you are creating. IPv4 (ipv4) is selected by default if you do not specify anything. You can also select dual-stacked (ipv4_ipv6). However, IPv6 is not supported.
jobId Number Required unless using a enrollmentId. This parameter is the job ID from a completed SPS or CPS request.
product Enumeration If multiple products are on the contract, specify the product to use when creating the edge hostname map. Valid products include Alta (alta), Ion Standard (ion_standard), Ion Media Advanced (ion_media), Ion Premier (ion_premier), and WAA (waa).
subscriptionId Number Deprecated. This parameter is the subscription ID, which references the subscription for the active certificate in CPS and includes information needed to create a new edge hostname.

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:

Parameter Type Description
spsId Number The ID number for a completed SPS request.
resourceLocation String The URL path component to use to check on the status of an SPS request.

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:

Code Description
200 OK
202 Accepted. The submission was accepted and will be processed accordingly.
400 Bad Request. Please provide all the required parameters.
403 User is not authenticated.
404 The requested resource is not found.
500 There is a problem processing your request. Please try again later. The details are provided in the response body.

Last modified: 12/12/2016