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 ability to request new certificates, modify existing certificates, automatically renew certificates, and delete certificates. CPS also manages key Transport Layer Security (TLS) configurations, including cipher selection.

You can use this 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.

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

Most common users of CPS API are developers and architects. By leveraging CPS API, users can 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. To use this API, you should be familiar with the terminology and concepts specific to the Luna Control Center.

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 API call. In addition, SPS can provision the most common certificate types and can add alternative names to a SAN certificate. To perform advanced operations with certificates, use the CPS API. CPS API is Akamai’s comprehensive toolbox for creating and modifying certificates. Since CPS and SPS both use the same set of identifiers for certificates, you can use the enrollmentId returned by one system as input on requests to the other system.

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 (CSRs).
  • 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 depends on many factors, including the number of domains and the responsiveness of the organization. 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

Before you can access the CPS API, you need to make sure CPS has been added to your contract. CPS is part of your contract if you purchased any secure delivery product.To get started with this API:

Internal Versioning

Internal versioning of CPS API is managed by Content-Type and Accept headers. In order for a client to successfully reach a resource via HTTP request, the version header (or version header pair if both Content-Type and Accept are required) in the request needs to match exactly any of the versioned resources. Otherwise the API call will fail to map to an allowed resource.

The format of a typical CPS versioning header is: application/vnd.akamai.cps.${ENTITY_NAME}.${VERSION}+${MEDIA_TYPE}. E.g. application/vnd.akamai.cps.enrollment.v4+json.

API Concepts

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

X509 Certificates

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 a client browser to verify the authenticity of a website.

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

  • Single certificate: Associates a single domain 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, which offers greater flexibility.

  • SAN certificate: Uses multiple domain names. These Subject Alternative Names (SANs) allow you to secure up to 100 domain 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 that you obtain from a CA not integrated with CPS.

Certificate Authorities

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 two CAs:

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

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 typical CPS DV certificate expires in 90 days.

  • 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). An EV certificate generally expires in two years.

  • Third Party Validation: This is used for third party certificates. The expiration date of third-party certificates varies, since these certificates are issued outside of CPS.

Enrollments

A CPS enrollment is the most fundamental and definitive concept that behaves as a core container for all the operations that clients can perform within CPS.

CPS is a certificate life cycle management tool and a CPS enrollment is the agent in this tool that allows users display all the information about the process that certificate goes through from the time it was requested, through renewal or removal. Once you obtain a certificate, you can—but not necessarily have to—use it until it expires, in most cases a year from the date the CA issued the certificate. That being said, you can start a renewal process whenever you want given CPS timeline allows it, i.e. not too close to expiration, already a renewal in process etc.

When expiration date of an active certificate in an enrollment approaches, CPS automatically starts the renewal process for users’ convenience in order to prevent Denial of Service (DoS) due to expired certificates. Start date of auto-renewal for an about-to-expire certificate depends on the the validation type:

  • EV: 90 days before expiration
  • OV: 60 days before expiration
  • DV: 20 days before expiration

When an auto-renewal operation starts, CPS then automatically deploys the renewed certificate when it receives it from the CA.

Resources Related to Enrollments in the API

An enrollment, along with other operations, allows you to create and manage changes for an enrollment. Relevant types for enrollment operations are:

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, e.g. ak-akamai-recommended.
preferredCiphers String Akamai cipher profile name, e.g. ak-akamai-recommended.
sni Group - sni Server Name Indication (SNI).
signatureAlgorithm Constant - Signature Algorithm Algorithm used to sign the certificate.
changeManagement Boolean When enabled, you need to intervene and approve the enrollment state before a certificate will be deployed with current configuration 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 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 certificate details. 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. Pre-verify certificate. CPS may trigger pre-verification warnings that require acknowledgement through the API.

  4. Submit the CSR. CPS submits the certificate request to the certificate authority (CA) of your choice for signing. For Third-Party enrollments, you must call the API to extract the CSR to share with your CA for signing.

  5. Validate the certificate. The CA validates the certificate. For Let’s Encrypt, this may involve API calls and validation token configuration.

  6. Issue the certificate. The CA issues the certificate.

  7. Retrieve the certificate. CPS automatically retrieves the certificate and verifies that it is the correct certificate. For Third-Party enrollments, you must use the API to submit a signed certificate and trust chain to CPS.

  8. Post-verify certificate. CPS verifies the certificate against the CSR request, and may trigger post-verification warnings that require acknowledgement through the API.

  9. Confirm change management is enabled. CPS checks whether or not change management is on. If it is on, CPS deploys certificates to the staging network and prompts users to review and acknowledge Change Management before deploying to the production network. If Change Management is off, CPS automatically deploys the certificate to the network.

  10. Check when the certificate may deploy. CPS checks whether or not you set Change.statusInfo.deploymentSchedule to specify when the certificate can deploy, and CPS waits until after the date, if applicable, before deploying the certificate. If you did not set this information, CPS automatically deploys the certificate to the network.

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

  12. Renew the certificate. Most certificates expire a year from the date the CA issued it. CPS automatically restarts these steps to renew the certificate before certificate expires unless you schedule enrollment removal using Remove an Enrollment.

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 Change.allowedInput[n].type returned by Get Change Status to determine actions and headers supported, then use the Accept and Content-Type headers for the respective allowedInput value below to inspect or perform updates to the Change. The following table presents an overview of the different types and corresponding headers. The table helps you identify which headers you can use when performing Get Change Information and Update a Change operations.

Category Change.allowedInput[n].type API type Description Content-Type header Accept header
Change-Management change-management-info info / GET Change Management information provides acknowledgement status, and may include warnings about potential conflicts that may occur if you proceed with acknowledgement. N/A application/vnd.akamai.cps.change-management-info.v3+json
Change-Management change-management-info info / GET The Deployment currently deployed to the staging network. Acknowledging change-management continues deploying this configuration to the production network. N/A application/vnd.akamai.cps.deployment.v1+json
Change-Management change-management-info update / POST Acknowledge Change Management is required to proceed deploying the certificate to the production network. application/vnd.akamai.cps.acknowledgement-with-hash.v1+json application/vnd.akamai.cps.change-id.v1+json
Let’s Encrypt lets-encrypt-challenges info / GET Get Let’s Encrypt DvChallenges for a given change. N/A application/vnd.akamai.cps.dv-challenges.v1+json
Let’s Encrypt lets-encrypt-challenges update / POST Submit an Acknowledgement to inform CPS that Let’s Encrypt challenges have been made available and are ready for validation. application/vnd.akamai.cps.acknowledgement.v1+json application/vnd.akamai.cps.change-id.v1+json
Post-Verification post-verification-warnings info / GET Post-verification Warnings generated for a given change. Produced after CPS retrieves a certificate from a CA or when a client uploads a certificate. You must acknowledge post-verification warnings for the change to continue processing. N/A application/vnd.akamai.cps.warnings.v1+json
Post-Verification post-verification-warnings update / POST You must acknowledge post-verification warnings by submitting an Acknowledgement. application/vnd.akamai.cps.acknowledgement.v1+json application/vnd.akamai.cps.change-id.v1+json
Pre-Verification pre-verification-warnings info / GET Pre-verification Warnings can generate for a given change. CPS produces these after it retrieves a certificate from a CA or after a client uploads the certificate. Post-verification Warnings must be acknowledged for the change to continue processing. N/A application/vnd.akamai.cps.warnings.v1+json
Pre-Verification pre-verification-warnings update / POST You must acknowledge pre-Verification warnings by submitting an Acknowledgement. application/vnd.akamai.cps.acknowledgement.v1+json application/vnd.akamai.cps.change-id.v1+json
Third-Party third-party-csr info / GET Get Certificate Signing Request (CSR) for a Third-Party certificate. N/A application/vnd.akamai.cps.csr.v1+json
Third-Party third-party-csr update / POST Upload Third Party Certificate and Trust Chain. application/vnd.akamai.cps.certificate-and-trust-chain.v1+json application/vnd.akamai.cps.change-id.v1+json

Last modified: 10/26/2017