
- Overview
- Resources
- Usage
- SPS workflows
- Assumptions
- Endpoints
- SPS requests endpoint
- Creating an SPS request
- Certificate options
- Create OV SAN certificate and edge hostname
- Create a DV SAN certificate with edge hostname and prove control over the domain
- Add a domain name to a SAN certificate
- Retrieve information about the request
- Create a secure edge hostname with an existing certificate
- Data
- Errors
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 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.
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 need to include the groupId
and contractId
query
parameters, in order to associate the appropriate group and contract
with the request. Similarly, for GET operations, you need to
specify the groupId
and contractId
to determine exactly which
SPS requests you want to access.
You can use the Property Manager API
to retrieve contractId
and group
string values for your account.
PAPI may yield ID values with three-letter string prefixes. If present,
you need to strip out the prefix so that the ID only contains digits.
Then plug it into SPS as a query param value. See
ID prefixes
for more information on how to configure PAPI to always remove the
three-letter string prefixes.
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
anddvStatus.redirectPath
for each domain that must be validated. Configure your web server so that requests tofullPath
are redirected toredirectPath
. 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/ |
List SPS Requests | GET | /config-secure-provisioning-service/ |
Get an SPS Request | GET | /config-secure-provisioning-service/ |
Secure Edge Hostnames | ||
Create a Secure Edge Hostname | POST | /config-secure-provisioning-service/ |
Create a request
POST /config-secure-provisioning-service/
Example: /config-secure-provisioning-service/
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/
Example: /config-secure-provisioning-service/
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/
Example: /config-secure-provisioning-service/
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/
Example: /config-secure-provisioning-service/
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:
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.
You send a request to SPS with all the information needed to create a certificate and create a secure edge hostname.
SPS does some basic validation, then sends a request to CPS to create a certificate.
CPS validates the request information and sends a certificate signing request (CSR) to the CA.
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.
CPS deploys the certificate to the Akamai network. While CPS processes the certificate, SPS intermittently polls CPS to check the status of the certificate.
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.
The Secure Edge host API validates the request information and creates a new edge hostname on the Akamai network using the new certificate.
When SPS detects that the Secure Edge Host API created a secure edge hostname on the Akamai network, SPS marks the request as complete.
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:
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.
You send a request to SPS with all the information needed to modify the SAN certificate and create a secure edge hostname.
SPS validates the information, then sends a request to CPS to modify the specified SAN certificate.
CPS validates the request information and sends a new certificate signing request (CSR) to the CA.
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.
CPS deploys the certificate to the Akamai network. While CPS processes the certificate, SPS intermittently polls CPS to check the status of the certificate.
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.
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.
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:
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.
Send a request to SPS with all the information needed to create a new secure edge hostname.
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”
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 11754the
groupId
is 1001the 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
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:
Each domain will have a unique
dvStatus
JSON object returned from the HTTP GET operation. Take note of thedvStatus.fullPath
anddvStatus.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
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 theredirectPath
address.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.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:
Each domain will have a unique
dvStatus
JSON object returned from the HTTP GET operation. Take note of thedvStatus.fullPath
anddvStatus.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
Configure your web server to serve the specified
responseBody
for HTTP GET requests at thefullPath
URL. Do this for each domain that needs to be validated.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.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 thatwww.example.com
andwww.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 anenrollmentId
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. TheenrollmentId
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 ajobId
and aenrollmentId
, if you enter both parameters theenrollmentId
overrides thejobId
.
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 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 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:
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 theenrollmentId
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. |