Secure Provisioning Service API Data Model

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 Uses 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 a GET.

Parameter Type Description
Required
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.[n]  

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 Description
Required
jobId Number The job ID from a completed SPS or CPS request.
spsId Number The integer ID for a completed SPS request.
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.
Optional
dvStatus SpsRequest.requestList.dvStatus.[n] When you use a domain validated certificate, this encapsulates information about the certificate as detailed below.
parameters SpsRequest.requestList.parameters.[n] When the request’s information query parameter is true, this object described below reflects the initial request’s set of form parameters.
lastStatusChange String The last time the status of the SPS request changed.
resourceUrl String The URL to use to check on the status of an 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.[n]  

This object describes the information you need for each domain during domain validation.

Member Type Description
Required
domainName String The domain name you want to validate. Example: www.example.com
Optional
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.[n]  

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.

Member Type Description
Required
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 Description
Required
spsId Number The integer ID for a completed SPS request.
resourceLocation String This member corresponds to resourceUrl.
Optional
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

Member Type Description
Required
data POST.Results.data.[n] An array of objects that contain results from the CPS API.
size Number Describes the length of the array.

POST.Results.data.[n]  

Member Type Description
Required
results POST.Results.data.results This inner results object holds the IDs relevant to certificate management.
Optional
code null deprecated
data null deprecated
message null deprecated
text null deprecated

POST.Results.data.results

Member Type Description
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 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 Description
Required
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.
Optional
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.

Last modified: 3/31/2017