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
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).
- 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.
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:
Review the Get Started section on available tools.
Review Authorize Your Client in Luna to create your API access credentials and authorizations.
Get help from the developer community and provide feedback. You can also contact your account representative for support. We want to hear from you!
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 List Contracts and List Groups resources.
Internal versioning of CPS API is managed by
Accept headers. In order for a client to
successfully reach a resource via HTTP request, the version header (or version header pair if both
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:
When using this API, you should be familiar with the following concepts:
- X509 Certificates
- Certificate Authorities
- Resources Related to an Enrollments
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
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.
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:
- Let’s Encrypt
If you want to use a different CA, you must use a
certificate and CA.
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-partycertificates varies, since these certificates are issued outside of CPS.
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:
||Constant - Registration Authority||Registration Authority.|
||Constant - Validation Type||Domain and Organization validation type.|
||Constant - Certificate||Certificate Type.|
||Constant - Network Type||Network Type.|
||String||Akamai cipher profile name, e.g.
||String||Akamai cipher profile name, e.g.
||Group - sni||Server Name Indication (SNI).|
||Constant - Signature Algorithm||Algorithm used to sign the certificate.|
||Boolean||When enabled, you need to intervene and approve the enrollment state before a certificate will be deployed with current configuration to the network.|
||Group - CSR||Certificate Signing Request.|
||Group - Organization||Organization information for the CSR request.|
||Group - Contact||Organization’s administrator contact information for the CSR request.|
||Group - Contact||Organization’s technical contact information for the CSR request.|
||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:
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.
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.
Pre-verify certificate. CPS may trigger pre-verification warnings that require acknowledgement through the API.
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.
Validate the certificate. The CA validates the certificate. For Let’s Encrypt, this may involve API calls and validation token configuration.
Issue the certificate. The CA issues the certificate.
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.
Post-verify certificate. CPS verifies the certificate against the CSR request, and may trigger post-verification warnings that require acknowledgement through the API.
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.
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.
Deploy the certificate. CPS deploys the certificate on the network.
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
Clients have to inspect the Change.allowedInput[n].type
returned by Get Change Status
to determine actions and headers supported, then use the
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|
||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||
||info / GET||The Deployment currently deployed to the staging network. Acknowledging change-management continues deploying this configuration to the production network.||N/A||
||update / POST||Acknowledge Change Management is required to proceed deploying the certificate to the production network.||
||info / GET||Get Let’s Encrypt DvChallenges for a given change.||N/A||
||update / POST||Submit an Acknowledgement to inform CPS that Let’s Encrypt challenges have been made available and are ready for validation.||
||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||
||update / POST||You must acknowledge post-verification warnings by submitting an Acknowledgement.||
||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||
||update / POST||You must acknowledge pre-Verification warnings by submitting an Acknowledgement.||
||info / GET||Get Certificate Signing Request (CSR) for a Third-Party certificate.||N/A||
||update / POST||Upload Third Party Certificate and Trust Chain.||
Last modified: 10/26/2017