API
TrainingSupportCommunity

API concepts

To understand this API’s various URL resources and the data it exchanges, you need to familiarize yourself with these concepts:

Certificate

It’s an electronic document that identifies a company, such as the name of the company and address, a public key, and the digital signature of a CA based on that certification authority's private key. In a public-key encryption system, you can widely distribute public keys, but only the owner knows the paired private keys. Any person can encrypt content using the public key of the receiver, but only the receiver’s private key can decrypt the content.

Root certificate

It's a primary, self-signed certificate that meets the X.509 standard. This certificate identifies the certificate authority (CA) that signs a client's certificate.

Intermediate certificate

It's a secondary certificate that meets the X.509 standard. This certificate serves as an extra level of security and a link of trust that provides the necessary chaining to the trusted root certificate in a secure socket layer connection.

Certificate validation

When you create a certificate set along with its version, the API checks if the certificates are valid. After your CA set is activated, you can enable mutual authentication for the set in the Certificate Provisioning System.

Certificate is valid if:

  • it's a properly formed x509 (PEM encoded) certificate,
  • it has valid x509 CA bits set,
  • it's within the validity period,
  • it's a self-signed root certificate or an intermediate certificate,
  • it uses SHA-256 signature hash algorithm or better unless allowInsecureSha1 option is set.

🚧

Allow SHA-1 (insecure) setting

For best results, use SHA-256 or higher algorithm for certificates. The allowInsecureSha1 option is disabled by default. If you want to use SHA-1 signed CA certificates for this version, enable this option.

📘

End-entity (leaf) certificates

Mutual TLS Edge Truststore does not accept end-entity (leaf) certificates and returns a validation error if one is uploaded.

Certificate authority (CA)

It’s a trusted entity that signs certificates and can vouch for the identity of a website. You can use Certificate Provisioning System to integrate and generate certificates using two CAs:

If you want to use a different CA, you also need to use a third-party certificate.

Certificate set (CA set)

It’s a set of CA certificates, versioned to allow incrementally different sets. If you delete a CA set it becomes read-only, which means you can no longer perform any operations on it but you can access the history of its activities.

CA set version

It’s a revision of a given certificate set. When you create a CA set, it has no versions. You can activate the CA set on staging and production networks only after you create a version. Version numbers start at 1 and increment as you create new versions for a set. When you activate a certificate set on the production network, you activate a specific version of that set.

📘

Activating CA set versions on ​Akamai​ networks

Only one version of a CA set can be active on a network. The version on staging and production networks can be different.

You can modify a version as long as it's not activated on any network. Activating one version of a CA set on a network automatically deactivates any currently active version of the CA set on that network.

Activation

It specifies the network on which you want to activate your CA set. You can activate on the staging or production networks. Only one version can be active on either the staging or production network. When the activation process completes, the previously activated version becomes inactive. For the POST request to activate a CA set version, see the POST Activate a version API.

Deactivation

Before you delete a CA set, you need to deactivate its active version. When you delete a CA set, it is permanently removed from both staging and production networks and marked as Deleted. The deleted CA set becomes read-only and you can no longer perform operations on it (such as create version, activate version, etc.). For the POST request to deactivate a CA set version, see POST Deactivate a version API.

Edge certificate

It’s a certificate managed by ​Akamai​ Certificate Provisioning System (CPS) that enables secure content delivery on ​Akamai​.

PEM (Privacy enhanced mail)

It’s a file format for storing and sending cryptographic keys, certificates, and other data, based on a set of 1993 Internet Engineering Task Force (IETF) standards.

Truststore

It stores certificates from a Certificate Authority that verify that the client and all CAs are trustworthy in an SSL connection.
Truststore is an integral component of the Public Key Infrastructure (PKI) framework. It acts as a centralized storage facility for digital certificates issued by trusted Certificate Authorities and their associated public keys, which ensures the authenticity and security of online communication.

Mutual authentication (mTLS)

TLS mutual authentication is a process where both the client and the server present certificate identities to one another, and each verify the authenticity of the other's claimed identity using locally configured trusted CA certificates. This is in contrast to common TLS server authentication on the Web, where only the server presents its certificate identity claim and the client verifies the authenticity of that claim using its local truststore.