The Certificate Provisioning System API

The Certificate Provisioning System (CPS) provides full life cycle management of SSL/TLS certificates for your Akamai Secure Delivery Network applications. This includes allowing you to request new certificates, modify existing certificates, automatically renew certificates, and delete certificates. CPS also manages key Transport Layer Security (TLS) configuration including cipher selection.

You can use this REST API as part of setting a secure website to ensure that the delivery of content to and from that site is secure. The SSL/TLS certificates that CPS provides authenticate the secure connection that the browser makes during secure delivery. CPS generates and secures the private key of each certificate.

You can also use the CPS API with the Secure Provisioning Service (SPS) API. The SPS API provides a convenient mechanism to provision certificates and secure edge hostnames in a single REST call. In addition, SPS can provision the most common certificate types and can add alt 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.

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

Who Should Use This API

The CPS API allows developers and architects access to full life cycle management of SSL/TLS certificates for your Akamai Secure Delivery Network applications. This includes allowing you to request new certificates, modify existing certificates, and delete certificates. 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 CPS API, you need to make sure the CPS has been added to your contract. CPS is part of your contract if you purchased any secure delivery product.

Developers using this API should be familiar with:

  • SSL/TLS certificates
  • Certificate authorities (CAs)
  • How Akamai obtains certificates on the requester’s behalf, which includes the generation of public/private key pairs and certificate signing requests (CSR)s.
  • DNS
  • Edge Hostnames

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

Advances in certificate validation require contact between the CAs and the organization for which the certificate is being requested. Depending on the validation mechanism and certificate authority, the process requires different levels of participation from the organization. The timeline for this process is dependent on many factors including the number of domains and the responsiveness of the organization. Akamai’s experience is that while the process can take just a few days, it can extend to much longer periods. Customers should consider using Domain Validation for the most rapid provisioning.

Getting Started

To get started with this API:

You need to determine the IDs for your contracts and groups prior to using this API. Both operations are available through the Property Manager API (PAPI) using its Contracts and Groups resources.

CPS API Concepts

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

What Is a Certificate?

A digital certificate is an electronic document that includes a company’s identification information (such as the name and address of the company), a public key, and the digital signature of a Certification Authority (CA) based on that certification authority’s private key. You can think of a certificate as you would a license or passport that identifies your website. Having a certificate provides a way for to verify the authenticity of a website to a client browser.

Authentication offers a way to establish the identity of a website to a browser. A certificate contains the common name (CN) you want to use for the certificate. This is the fully qualified domain name for which you plan to use your certificate. CPS supports the following types of certificate:

  • Single certificate: Associates a single server with a single name.

  • Wildcard certificate: Secures an entire domain. A certificate for *.example.com secures www.example.com, mail.example.com, and any subdomain of example.com. If you do not know what domains you want to attach your certificate to, you should obtain a wildcard certificate. It can offer you flexibility.

  • SAN certificate: Uses multiple server names. These subject alternative names (SAN)s allow you to secure up to 100 server names with one certificate. These certificates address the need to secure multiple names across different domains. You can update a SAN certificate at any time to add more names, up to the capacity of the certificate.

  • Wildcard SAN certificate: Uses wildcard certificates with Subject Alternative Names. You can only use wildcard SAN certificates from Symantec with CPS.

  • Third party certificate: Uses a signed certificate obtained by you from a CA not integrated with CPS.

What Is a Certificate Authority?

A Certificate Authority (CA) is a trusted entity that signs certificates and can vouch for the identity of a website. CPS integrates and automates certificate generation with three CAs:

If you want to use a different CA, you must use a third party certificate and CA.

What Is Validation?

When a CA gets a request for a certificate and verifies your identity, it validates the certificate. There are four types of validation:

  • Domain Validation (DV): A lower level of validation. The CA validates that you have control of the domain. A DV certificate expires in one year.

  • Organization Validation (OV): A higher level of validation. The CA validates whether or not the company is valid, if it is registered, and if the business contact legitimately works at the company. An OV certificate generally expires in one year.

  • Extended Validation (EV): The highest level of validation in which you must have signed letters and notaries sent to the CA before signing. Wildcard certificates cannot be EV certificates because an EV certificate requires you to be explicit about all the subject alternative names (SANs).

  • Third party Validation: This is used for third party certificates. The validation type of these is unknown to CPS since these certificates are issued outside of CPS.

What Is an Enrollment?

An enrollment displays all the information about the process that your certificate goes through from the time you request it, through renewal, and as you obtain subsequent versions. CPS is a certificate life cycle management tool. Once you obtain a certificate, you use it until it expires, in most cases a year from the date the CA issued the certificate. CPS automatically starts the renewal process 45 days before the old certificate expires, and then automatically deploys the renewed certificate when it receives it from the CA. There are four types of enrollment in CPS:

  • Domain validation enrollments (DV): Where the CA, which is Let’s Encrypt, validates that you have control of the domain.

  • Organization validation enrollments (OV): Where the CA, which is Symantec, validates whether or not the company is valid, if it is registered, and if the business contact legitimately works at the company.

  • Extended validation (EV) enrollments: The highest level of validation in which you must have signed letters and notaries sent to the CA before signing. Wildcard certificates cannot be EV certificates because an EV certificate requires you to be explicit about all the subject alternative names (SANs).

  • Third party validation enrollments: Where the CA is a CA of your choice. CPS does not know the validation type of these certificates since these certificates are issued outside of CPS.

Resources Related to Enrollments in the API

An enrollment allows you to create and manage changes for a certificate. The types are relevant for this Enrollment-related operations:

Property Type Description
ra Constant - Registration Authority Registration Authority
validationType Constant - Validation Type Domain and Organization validation type
certificateType Constant - Certificate Certificate Type
networkType Constant - Network Type Network Type
mustHaveCiphers String Akamai cipher profile name, f.x. ak-akamai-recommended
preferredCiphers String Akamai cipher profile name, f.x. ak-akamai-recommended
sni Group - sni Server Name Indication (SNI)
signatureAlgorithm Constant - Signature Algorithm Algorithm used to sign the certificate
changeManagement Boolean Enabling change management will require user intervention before a certificate will be deployed to the network.
csr Group - CSR Certificate Signing Request
org Group - Organization Organization information for the CSR request
adminContact Group - Contact Organization’s Administrator contact information for the CSR request
techContact Group - Contact Organization’s Technical contact information for the CSR request
thirdParty Group - ThirdParty Information for certificates signed by RAs other than Akamai’s integrated RAs

About the CPS Workflow

An enrollment displays all the information about the process that your certificate goes through from the time you request it, through renewal, and as you obtain subsequent versions. CPS is a certificate life cycle management tool. Once you obtain a certificate, you use it until it expires, in most cases a year from the date the CA issued the certificate. CPS automatically starts the renewal process 45 days before the old certificate expires, and then automatically deploys the renewed certificate when it receives it from the CA. The CPS workflow is as follows:

  1. Collect all the information you need to get a certificate. This includes, the name, address, and phone number of your organization, and contact information for someone at your company and a representative from Akamai.

  2. Create the certificate signing request (CSR). You must use CPS to create a request for a certificate from your CA. CPS stores the private key for the certificate when you create the request.

  3. Submit the CSR. CPS submits the certificate request to the certificate authority (CA) of your choice for signing.

  4. Validate the certificate. The CA validates the certificate.

  5. Issue the certificate. The CA issues the certificate.

  6. Retrieve the certificate. CPS automatically retrieves the certificate and verifies that it is the correct certificate.

  7. Check to see whether or not change management is on. CPS checks whether or not change management is on. If it is on, CPS does not automatically deploy the certificate to the network. If it is off, CPS automatically deploys the certificate to the network.

  8. Check for a scheduled date before which, CPS cannot deploy the certificate. CPS checks whether or not you set a date and time before which, CPS cannot deploy the certificate to the network. If you set this information, CPS waits until after the date and time to deploy the certificate. If you did not set this information, CPS automatically deploys the certificate to the network.

  9. Deploy the certificate. CPS deploys the certificate on the network.

  10. Renew the certificate. Most certificates expire a year from the date the CA issued it. CPS automatically restarts these steps to renew the certificate 45 days before it expires unless you specify that you do not want to automatically renew the certificate.

Change Input Content Type Mapping

A Change may allow for updates to be made under certain conditions. The type of updates allowed is internal to the system, and is determined by the state of the change as well as the specific enrollment type. Clients have to inspect the allowedInput’s type returned for a Change to determine actions and headers supported, and in turn use the Accept and Content-Type headers to inspect or perform changes to the Change. A full overview of the different types and corresponding headers can be found below.

Type Action type Content-Type Accept header
third-party-certificate info / GET N/A application/vnd.akamai.cps. csr.v1+json
third-party-certificate update / POST application/vnd.akamai.cps. certificate-and-trust-chain.v1+json application/vnd.akamai.cps. change-id.v1+json
post-verification-warnings-acknowledgement info / GET N/A application/vnd.akamai.cps.change-management-info.v1+json
post-verification-warnings-acknowledgement update / POST application/vnd.akamai.cps. acknowledgement.v1+json application/vnd.akamai.cps. change-id.v1+json
change-management info / GET N/A application/vnd.akamai.cps.change-management-info.v1+json
change-management update / POST application/vnd.akamai.cps.acknowledgement-with-hash.v1+json application/vnd.akamai.cps. change-id.v1+json
lets-encrypt-challenges update / POST application/vnd.akamai.cps. acknowledgement.v1+json application/vnd.akamai.cps. change-id.v1+json

What Requests Can I Make?

If you want to know what requests you can make to a particular resource in the API, you can use OPTIONS with the Accept header. For example:

OPTIONS /cps/v2/enrollments/

Accept: application/vnd.akamai.cps.options.v1+json

The response appears as follows:

200 OK

Content-Type: application/vnd.akamai.cps.options.v1+json

{
  "path" : "/cps/v2/enrollments/",
  "methods" : {
    "OPTIONS" : [ {
      "produces" : [ "application/vnd.akamai.cps.options.v1+json" ],
      "consumes" : [ "*/*" ]
    } ],
    "GET" : [ {
      "notes" : [ "Get list of enrollment URLs." ],
      "produces" : [ "application/vnd.akamai.cps.enrollment-locations.v1+json" ],
      "consumes" : [ ]
    }, {
      "notes" : [ "Get list of enrollments." ],
      "produces" : [ "application/vnd.akamai.cps.enrollments.v1+json" ],
      "consumes" : [ ]
    } ],
    "POST" : [ {
      "notes" : [ "Create an enrollment." ],
      "produces" : [ "application/vnd.akamai.cps.enrollment-status.v1+json" ],
      "consumes" : [ "application/vnd.akamai.cps.enrollment.v1+json" ]
    } ]
  }

You can optionally use the notes field to obtain more information about the purpose produces and consumes combination. In the example above, the first item in the GET list is to get a list of enrollment URLs, and the second is the get a list of enrollments.


Last modified: 10/25/2016