Secure Provisioning Service API

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.

About This Guide

This API documentation contains the following sections:

  • Uses provides information about common use cases for this API.

  • Debug describes the API’s error-reporting system, and lists the range of HTTP status codes.

  • Data provides details on the data the API exchanges.

  • Resources provides information about each API operation.

This section contains the following information about SPS:

  • Who Should Use this API describes what you should be familiar with as a developer about to use this API.

  • Getting Started provides information on what you need to do before using this API.

  • Concepts provides information on general SPS concepts.

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 the Luna 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

Getting Started

To get started with this API:

  • Contact your Akamai representative to enable SPS for your account.

  • Review the {OPEN} API Introduction section on available tools.

  • Review the {OPEN} API Provisioning section to create your OPEN API access credentials and authorizations, making sure you enable read/write access for this API grant.

  • Get help from the {OPEN} developer community and provide feedback. You can also contact your Akamai representative for support.

Concepts

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

  • Group IDs and Contract IDs

  • Secure Edge Hostnames

  • Certificates

  • SHA

  • SNI

  • Domain Validation

About Group and Contract IDs

When using this API, your level of access depends on the groups and contracts for which your Luna 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 must include the groupId and contractId in the query parameter, in order to associate the appropriate group and contract with the request. Similarly, for the GET operations, you must specify the groupId and contractId to determine exactly which SPS requests you want to access.

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 and dvStatus.redirectPath for each domain that must be validated. Configure your web server so that requests to fullPath are redirected to redirectPath. 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.


Last modified: 12/12/2016