Manage client certificates

Securely manage client certificates to establish a mutual authentication (mTLS) session between Akamai edge servers and the origin.

1. Prep

To create and use client certificates for an mTLS session, you need properties from the Property Manager API.

2. Create a client certificate

Depending on the type of client certificate you want to use, you can create:

• An Akamai-signed client certificate. Its lifecycle is entirely handled on the Akamai side.
• A third-party signed client certificate. Its lifecycle is fully managed by your organization.

Use the New-MOKSClientCert command to create an Akamai-signed or third-party client certificate. You can use this command in two ways:

• Specify the client certificate's settings using individual parameters. Make sure to provide an appropriate signing entity for your client certificate, either AKAMAI or THIRD_PARTY, in the -Signer parameter.

  CommandOutput

  New-MOKSClientCert -CertificateName 'my-akamai-client-cert' -CommonName 'example.com' -ContractID 'C-0N7RAC7' -GroupID 12345 -Geography 'CORE' -SecureNetwork 'STANDARD_TLS' -Signer 'AKAMAI' -NotificationEmails 'jsmith@example.com'
  

  certificateId      : 123
  certificateName    : my-akamai-client-cert
  signer             : AKAMAI
  secureNetwork      : STANDARD_TLS
  geography          : CORE
  keyAlgorithm       : RSA
  subject            : /C=US/O=Akamai Technologies, Inc./OU=23456 A-CCT1234 12345/CN=my-akamai-client-cert/
  notificationEmails : {jsmith@example.com}
  createdDate        : 8/21/2025 1:26:30 PM
  createdBy          : jsmith@example.com
  

• Provide the client certificate's settings in a variable as a hashtable, PSCustomObject, or JSON string, and then pass the variable in the -Body parameter of the New-MOKSClientCert command.

$myAkamaiClientCert = @{
    geography = "CORE"
    notificationEmails = @(
        "jsmith@example.com"
    )
    secureNetwork = "STANDARD_TLS"
    signer = "AKAMAI"
    certificateName = "my-akamai-client-cert"
    contractId = "C-0N7RAC7"
    groupId = 12345
}

New-MOKSClientCert -Body $myAkamaiClientCert

$myAkamaiClientCert = '{
    "geography": "CORE",
    "notificationEmails": [
        "jsmith@example.com"
    ],
    "secureNetwork": "STANDARD_TLS",
    "signer": "AKAMAI",
    "certificateName": "my-akamai-client-cert",
    "contractId": "C-0N7RAC7",
    "groupId": 12345
}'

New-MOKSClientCert -Body $myAkamaiClientCert

Note: Using the -Body parameter in the New-MOKSClientCert command is more complex but offers full control over the client certificate's settings. In contrast, specifying the settings with individual parameters is simpler but provides limited functionality.

Akamai-signed client certificates

For Akamai-signed client certificates, the certificate is automatically signed. Additionally, the first version of the certificate is created for you. The version initially has the DEPLOYMENT_PENDING status. It changes to DEPLOYED after 5–10 minutes. You can check your certificate version's deployment status with the Get-MOKSClientCertVersion operation by passing the -CertificateName or -CertificateID parameter.

Get-MOKSClientCertVersion -CertificateName 'my-akamai-client-cert'

version            : 1
versionGuid        : 1abcdef2-g34h-56ij7k-l89m-no0pqr12346
versionAlias       : CURRENT
subject            : /C=US/O=Akamai Technologies, Inc./OU=23456 A-CCT1234 12345/CN=my-akamai-client-cert/
issuer             : 23456 Account CA G1
keyAlgorithm       : RSA
keySizeInBytes     : 2048
signatureAlgorithm : SHA256_WITH_RSA
issuedDate         : 8/22/2025 9:41:41 AM
expiryDate         : 11/20/2025 9:41:41 AM
status             : DEPLOYED
deployedDate       : 8/21/2025 1:40:03 PM
createdBy          : jsmith@example.com
createdDate        : 8/21/2025 1:26:35 PM
validation         : @{errors=System.Object[]; warnings=System.Object[]}
certificateBlock   : @{certificate=-----BEGIN CERTIFICATE-----
                     MIID <sample - removed for readability> .... Mweq
                     -----END CERTIFICATE-----; keyAlgorithm=RSA; trustChain=-----BEGIN CERTIFICATE-----
                     MIID <sample - removed for readability> .... Mweq
                     -----END CERTIFICATE-----}

The version has a default lifespan of three months. Once the version expires, it's automatically rotated. See the Rotate a client certificate version section for details.

If it's the first Akamai-signed client certificate that you created on your account, mTLS Origin Keystore generates an account CA (certificate authority) certificate. It identifies the account CA and includes a public key and a digital signature based on the account CA's private key. To check the account CA certificate's details, run the Get-MOKSCACert operation by passing an optional -Status parameter with at least one of these values separated by commas: QUALIFYING, CURRENT, PREVIOUS, or EXPIRED.

Get-MOKSCACert -Status 'CURRENT'

id                 : 123
version            : 1
accountId          : A-CCT1234
subject            : /C=US/O=Akamai Technologies, Inc./OU=Akamai CDN mTLS/CN=23456 Account CA G1/
commonName         : 23456 Account CA G1
keyAlgorithm       : RSA
keySizeInBytes     : 4096
signatureAlgorithm : SHA256_WITH_RSA
certificate        : -----BEGIN CERTIFICATE-----
                     MIID <sample - removed for readability> .... Mweq
                     -----END CERTIFICATE-----
                     
status             : CURRENT
issuedDate         : 7/1/2025 10:21:33 AM
expiryDate         : 6/30/2030 10:21:33 AM
createdBy          : jsmith@example.com
createdDate        : 7/1/2025 10:21:28 AM

📘

An account CA isn't created when you manage only third-party certificates on your account.

Third-party client certificates

Regarding third-party client certificates, the client certificate's version is created with the AWAITING_SIGNED_CERTIFICATE status. You can check your certificate version's deployment status with the Get-MOKSClientCertVersion operation by passing the client certificate's name or ID.

Get-MOKSClientCertVersion -CertificateName 'my-third-party-client-cert'

version        : 1
versionGuid    : 987z6yx-5432-109w-8765-43vu21ts0rqp
keyAlgorithm   : RSA
keySizeInBytes : 2048
status         : AWAITING_SIGNED_CERTIFICATE
createdBy      : jsmith@example.com
createdDate    : 8/22/2025 10:25:01 AM
validation     : @{errors=System.Object[]; warnings=System.Object[]}
csrBlock       : @{csr=-----BEGIN CERTIFICATE REQUEST-----
                 MIID <sample - removed for readability> .... Mweq
                 -----END CERTIFICATE REQUEST-----; keyAlgorithm=RSA}

Once you've created your client certificate with its first version, you need to sign that version before deployment. To do that:

1. From the Get-MOKSClientCertVersion operation's response, copy a PEM-formatted certificate signing request (CSR) that you can find in the csrBlock attribute.

2. Send the retrieved CSR to your chosen certificate authority (CA) for signing.

3. Upload your signed certificate for deployment with the Complete-MOKSClientCertVersion operation by passing the client certificate's name or ID.

   Note: The certificate must be in PEM format. If it was returned to you in a different format, convert it to PEM format using OpenSSL commands. For example:

   • Convert a CRT file to PEM.

     openssl x509 -in certificate.crt -outform PEM -out certificate.pem

   • Convert a PKCS12 (.pfx or .p12) file to PEM.

     openssl pkcs12 -in certificate.pfx -out certificate.pem

   You can upload the signed certificate in two ways with the Complete-MOKSClientCertVersion command:

   • Provide the path to your PEM-formatted certificate in the -CertificateFile parameter.

     Command

     Complete-MOKSClientCertVersion -CertificateName 'my-third-party-client-cert' -Version '1' -CertificateFile './my-signed-cert.pem'
     

   • Provide your PEM-formatted certificate in a variable as a hashtable, PSCustomObject, or JSON string, and then pass the variable in the -Body parameter.

     Command: HashtableCommand: JSON string

     $mySignedCert = @{
         certificate = "-----BEGIN CERTIFICATE REQUEST-----\nMIID <sample - removed for readability> .... Mweq\n-----END CERTIFICATE REQUEST-----"
     }
     
     Complete-MOKSClientCertVersion -CertificateName 'my-third-party-client-cert' -Version '1' -Body $mySignedCert
     

     $mySignedCert = '{
         "certificate": "-----BEGIN CERTIFICATE REQUEST-----\nMIID <sample - removed for readability> .... Mweq\n-----END CERTIFICATE REQUEST-----"
     }'
     
     Complete-MOKSClientCertVersion -CertificateName 'my-third-party-client-cert' -Version '1' -Body $mySignedCert
     

   The Complete-MOKSClientCertVersion operation doesn't return any output. You can check the certificate's deployment status with the Get-MOKSClientCertVersion operation.

   Once the certificate is uploaded, the version initially has the DEPLOYMENT_PENDING status. It changes to DEPLOYED after 5–10 minutes.

To rotate versions, see the Rotate a client certificate version section for details.

3. Add property behaviors

Configure your property to point to the DEPLOYED client certificate version you want to use to establish an mTLS session.

1. Get your property's rule tree as JSON snippets. The output is a directory at your current location containing your rule's configurations.

   Command

   Get-PropertyRules -PropertyName 'my-property-1' -PropertyVersion 'latest' -OutputSnippets -OutputDirectory './my-property-rules'
   

2. Add the mtlsOriginKeystore behavior to your property rules' main.json. For this behavior:

   • Set the enable attribute to true to enable the behavior.
   • In the clientCertificateVersionGuid attribute, assign your client certificate's versionGuid to the property. This authenticates your origin with the edge server.
   • Set the authClientCert attribute to true to initiate the mTLS connection between the edge server and origin. If set to false, this initiates a standard TLS connection to the origin.
   JSON

   {
     "behaviors": [
       {
         "name": "mtlsOriginKeystore",
         "options": {
           "enable": true,
           "clientCertificateVersionGuid": "a123bcd-45ef-67g09-hi01-j234klm5no6789",
           "authClientCert": true
         }
       }
     ]
   }
   

   For the Akamai-signed client certificate type, the version GUID is automatically associated with the versionAlias (CURRENT or PREVIOUS) of the client certificate. This ensures that no updates to the rule tree are required after version rotation.

   For third-party client certificates, the version GUID is reused only if you use an alias versionGuid, labelled as CURRENT or PREVIOUS in the versionAlias attribute. For non-alias versions, you need to manually update the rule tree to reflect the new version GUID whenever you update the client certificate version in the property. If the version isn't deployed, the property returns an error. See Rotate a client certificate version for details.

   If you want to reuse the certificate's version GUID, ensure you always link to the CURRENT alias version to keep your certificate up to date. The CURRENT version will always point to the latest version where the certificate was uploaded.

3. Add your updated rules to your property, pointing to the appropriate directory.

   Send your entire rule tree back. Rules not returned are removed from your property.

   Command

   Set-PropertyRules -PropertyName 'my-property-1' -PropertyVersion 'latest' -InputDirectory './my-property-rules' -VersionNotes 'Adding a Keystore setting'
   

   The output returns your rule tree along with any errors or warnings upon upload.

If you’ve configured a client certificate for an ENHANCED_TLS network, the property also needs to use an Enhanced TLS edge hostname ending in edgekey.net. Otherwise, you won't be able to link the client certificate to the property.

4. Activate a property

To activate the property containing your newly added client certificate, provide a value for the network, staging or production, and then activate your property using the New-PropertyActivation command or its alias Deploy-Property.

Deploy-Property -PropertyName 'my-property' -PropertyVersion 'latest' -Network 'Staging' -NotifyEmails 'jsmith@email.com'

activationLink                                                                                      activationId
--------------                                                                                      ------------
/papi/v1/properties/prp_12345/activations/atv_67890?contractId=ctr_C-0N7RAC7&groupId=grp_12345      atv_67890

You can link your client certificate to a property that is activated on the staging network. However, to make the certificate work, the property must be activated on the production network.

Other actions

Update a client certificate

You can only update the certificateName and notificationEmails arguments in the Akamai-signed and third-party client certificate resources. You can do this with the Set-MOKSClientCert operation. In the command, specify a -CertificateName or -CertificateID for which you want to update the settings, and use one of these ways to update them:

• Specify a new certificate name and notification emails as individual parameters.

  Command

  Set-MOKSClientCert -CertificateName 'my-client-cert' -NewName 'my-updated-client-cert-name' -NotificationEmails 'jsmith@example.com, jasmith@example.com'
  

• Provide a new certificate name and notification emails in a variable as a hashtable, PSCustomObject, or JSON string, and then pass the variable in the -Body parameter of the Set-MOKSClientCert command.

  Command: HashtableCommand: JSON string

  $myUpdatedCert = @{
      certificateName = "my-updated-client-cert-name"
      notificationEmails = @(
          "jsmith@example.com",
          "jasmith@example.com"
      )
  }
  
  Set-MOKSClientCert -CertificateName 'my-client-cert' -Body $myUpdatedCert
  

  $myUpdatedCert = '{
      "certificateName": "my-updated-client-cert-name",
      "notificationEmails": [
          "jsmith@example.com",
          "jasmith@example.com"
      ]
  }'
  
  Set-MOKSClientCert -CertificateName 'my-client-cert' -Body $myUpdatedCert
  

The Set-MOKSClientCert operation doesn't return any output.

To have a client certificate with a different version, see the Rotate a client certificate version section for details.

Rotate a client certificate version

Use version rotation to keep your client certificates up to date and preserve their properties by extending their validity periods.

You can't rotate if a version is in the DEPLOYMENT_PENDING or DELETE_PENDING status for the Akamai-signed or third-party client certificate.

Akamai-signed client certificates

For Akamai-signed client certificates, the first version is added automatically to the client certificate upon creation and is aliased as CURRENT. This certificate type can have up to two versions. They're marked with the versionAlias attribute of the CURRENT or PREVIOUS value, and their default lifespan is three months. Versions are automatically rotated by the server every time a given version expires.

If you want to manually rotate your client certificate versions, here are a few things to take into account:

• For certificates with one version, forcing a rotation creates a new version with a higher number, which becomes the CURRENT version.
• For certificates with two versions, forcing a rotation removes the oldest version. The most recent version becomes CURRENT, and the version that was previously CURRENT is downgraded to PREVIOUS.
• If you remove the CURRENT version when two versions exist, the PREVIOUS version becomes the new CURRENT.
• The versionGuid automatically links to the CURRENT or PREVIOUS version, so you can reuse it in your property without updating the rule tree after rotation.

Run the New-MOKSClientCertVersion operation to manually rotate versions by passing a client certificate's name or ID. A new version is created with an initial status of DEPLOYMENT_PENDING, which changes to DEPLOYED after 5–10 minutes.

New-MOKSClientCertVersion -CertificateName 'my-akamai-client-cert'

version            : 2
versionGuid        : 1abcdef2-g34h-56ij7k-l89m-no0pqr12346
versionAlias       : CURRENT
subject            : /C=US/O=Akamai Technologies, Inc./OU=23456 A-CCT1234 12345/CN=my-akamai-client-cert/
issuer             : 23456 Account CA G1
keyAlgorithm       : RSA
keySizeInBytes     : 2048
signatureAlgorithm : SHA256_WITH_RSA
issuedDate         : 8/22/2025 9:41:41 AM
expiryDate         : 11/20/2025 9:41:41 AM
status             : DEPLOYMENT_PENDING
createdBy          : jsmith@example.com
createdDate        : 8/21/2025 1:26:30 PM
validation         : @{errors=System.Object[]; warnings=System.Object[]}
certificateBlock   : @{certificate=-----BEGIN CERTIFICATE-----
                     MIID <sample - removed for readability> .... Mweq
                     -----END CERTIFICATE-----; keyAlgorithm=RSA; trustChain=-----BEGIN CERTIFICATE-----
                    MIID <sample - removed for readability> .... Mweq
                     -----END CERTIFICATE-----}

Third-party client certificates

For third-party client certificates, the client certificate versions aren't automatically rotated. You need to do this manually. You can have up to five versions for this certificate type.

When you deploy a given version, it's included as a separate version record with a different versionGuid. This record is additionally marked with the versionAlias attribute of the CURRENT or PREVIOUS value.

There can be up to two alias versions, CURRENT or PREVIOUS, at the same time. The most recently deployed or pending deployment version is labeled as CURRENT, and the previously deployed CURRENT version (if any) is marked as PREVIOUS.

Here are a few things to consider about alias versions in third-party client certificates:

• If you remove the CURRENT version when CURRENT and PREVIOUS alias versions exist, the PREVIOUS version becomes the new CURRENT.
• The alias versionGuid allows you to reuse it in your property without updating the rule tree after version rotation.

To manually rotate versions:

1. Generate a new version with the New-MOKSClientCertVersion operation.

   CommandOutput

   New-MOKSClientCertVersion -CertificateName 'my-third-party-client-cert'
   

   version        : 2
   versionGuid    : 987z6yx-5432-109w-8765-43vu21ts0rqp
   keyAlgorithm   : RSA
   keySizeInBytes : 2048
   status         : AWAITING_SIGNED_CERTIFICATE
   createdBy      : jsmith@example.com
   createdDate    : 8/26/2025 10:34:05 AM
   validation     : @{errors=System.Object[]; warnings=System.Object[]}
   csrBlock       : @{csr=-----BEGIN CERTIFICATE REQUEST-----
                   MIID <sample - removed for readability> .... Mweq
                   -----END CERTIFICATE REQUEST-----; keyAlgorithm=RSA}
   

2. Send your client certificate's name or ID in the Get-MOKSClientCertVersion operation to retrieve a CSR for your new version.

3. Send the CSR to your chosen CA for signing.

4. Upload your signed certificate for deployment with the Complete-MOKSClientCertVersion operation.

5. Update the mTLS Origin Keystore behavior on your property's rule tree by adding a newly generated versionGuid to the clientCertificateVersionGuid argument.

6. Activate your property with the new client certificate version.

If you reach the limit of five versions for your certificate and want to rotate, first, you need to delete a version before adding a new one.

Delete a client certificate version

You can delete a specific client certificate version only if it isn't used in any property activated on the production network.

Note that deleting the last version of your client certificate removes the entire certificate.

To delete a version:

1. Verify if a specific client certificate version isn't assigned to a property. Run the List client certificate versions operation with the includeAssociatedProperties query parameter enabled.

2. Search for the versionGuid you want to delete and check the properties attribute to verify if that version is used with any property. The properties argument lists only properties activated on the production network.

3. If a version is assigned to a property, unlink it from the property by updating the mTLS Origin Keystore behavior on the property's rule tree to use another version.

   Notes:

   • For Akamai-signed certificates, the version is automatically rotated and deployed. As a result, when linking a property to an alias versionGuid of that certificate, no update to the property's rule tree is needed.
   • For third-party certificates, you need to manually deploy a new version, but linking the property with the alias versionGuid doesn't require any changes to the property's rule tree.

4. Once the version is unlinked from the property, remove it with the Remove-MOKSClientCertVersion operation by specifying the client certificate's ID or name and the version you want to delete.

   The operation doesn't return any output.

   Command

   Remove-MOKSClientCertVersion -CertificateID 123 -Version '1'
   

   Deleting a version can leave gaps in the version sequence. For example, if you delete the latest or highest version number, the next version you create will skip that number.

   When deleting the last deployed version of an Akamai-signed or third-party certificate, its status changes to DELETE_PENDING for up to 24 hours before the entire certificate is permanently deleted from the server. If you attempt to recreate that certificate during this 24-hour window while the deletion is in progress, you receive an error. Non-deployed versions are deleted instantly.

5. Verify if the version has been deleted:

   1. Run the Get-MOKSClientCertVersion operation.
   2. If the version isn't present on the operation's response, it's been deleted.

   If you included your email in the -NotificationEmails parameter upon client certificate creation, you should receive a notification confirming the version deletion.