POST Certificates/Retrieve

Returns the available certificate data and optional private key information for an enrolled certificate. The response includes a CertificateData field containing the certificate in the requested Format, encoded as a Base64 string. To get a usable certificate file, Base64-decode the CertificateData value and save it with the appropriate file extension. If you want to download the certificate directly as a file instead, call GET Certificates/Retrieve.

Requirements

  • Permissions:  The caller must have Read permission and Private Key Read permission to the Certificate object.
  • Token scope:  Certificate:Manage

Headers

  • Content type: Content-Type:application/json.

  • Token: The bearer access token that you received. For example, Authorization:Bearer xxxxxx==. For more information, see Passing a bearer token in your API calls.

Parameters

Input parameters

Name

Description

CertificateDN

The Trust Protection Foundation Distinguished Name (DN) of the certificate.

Format

The certificate format for the return data. This parameter is required; omitting it returns HTTP 400.

Format values are case-insensitive. Spaces and special characters in format names (such as #) can be omitted. For example, PKCS #12 and pkcs#12 are both accepted.

Format value File extension Description
Base64 .pem or .cer Certificate in PEM format. The file extension is .pem when the chain or private key is included, .cer otherwise. Mime-type: application/x-pem-file.
Base64 (PKCS #8) .pem Certificate in PEM format with the PKCS#8 encoded private key. Mime-type: application/x-pem-file.
DER .cer Raw binary certificate. Mime-type: application/x-x509-ca-cert.
JKS .jks Java Keystore format. Requires KeystorePassword. Mime-type: application/octet-stream.
PKCS #7 .p7b Certificate with optional chain in PKCS#7 format. Mime-type: application/x-pkcs7-certificates.
PKCS #12 .pfx Certificate in PKCS#12 format. Use with IncludePrivateKey and Password to include the private key. Mime-type: application/x-pkcs12.

FriendlyName

The label or alias to use for Base64, JKS, or PKCS #12 formats. Required for the JKS format.

IncludeChain (Optional)

When the Format is Base64, Base64 (PKCS #8), PKCS #7, PKCS #12, or JKS, you can include the parent or root chain in the return data.

  • true: Include the root chain. Use RootFirstOrder to set the order. The data appears after any private key information.
  • false: Omit the root chain.

IncludePrivateKey (Optional)

When the Format is Base64 (PKCS #8), PKCS #12, or JKS, you can specify whether to return the private key:

  • false: No private key.
  • true: Default. Create a private key based on KeystorePassword.

KeystorePassword

 If the Format is JKS, you must set this value. Use the same requirements as required for Password.

Password

If the IncludePrivateKey value is true, this value must be set.

The password must meet the Private Key Export rule for the certificate. This is the rule set on the certificate's policy folder. If the folder doesn't set a rule, the default Private Key Export rule is used. .

IMPORTANT  Spaces at the start or end are kept as part of the password.. To open the private key file later, you must type exactly the same password.

For more information, see Global password rules.

RootFirstOrder

(Optional)

In the REST response, the order of the certificate chain of trust. Use when IncludeChain is true.

  • true: Set the root certificate first, followed by intermediate certificates, and finally the end entity certificate.
  • false: Default. Set the end entity first, followed by intermediate certificates, and finally the root certificate.

WorkToDoTimeout

(Optional) The maximum wait time for certificate retrieval.

Overrides the Platforms tree setting for the Certificate API ToDo Timeout setting. The maximum number of seconds to wait for the ToDo operation to complete. The default is zero seconds with a maximum value of 120 seconds. For example:WorkToDoTimeout: 60. For more information, see Certificates API configuration.

Returns

Response description

Name

Description

HTTP 200

If the certificate is currently in enrollment, provisioning, or in error, the response contains only the current Status and processing Stage of the Certificate object.

  • CertificateData: The certificate in the Base64 with the capability for you to convert it to the specified Format. The certificate data is only available after certificate enrollment completes. If the caller supplied private key parameters and a private key is present in the Secret Store, Trust Protection Foundation includes the private key data.
  • Filename: The suggested filename for the certificate data (in case the caller wants to save the certificate data in a file).
  • Format: A reminder of the intended Format that is imbedded in the CertificateData.
    • Base64or Base64 (PKCS #8) : application/x-pem-file

      The CertificateData response value is the certificate data in the requested format, encoded as a Base64 string for JSON transport. To get a usable certificate file, decode the Base64 data and save it with the appropriate file extension for the format you requested (for example, .pem for Base64, .pfx for PKCS #12, .p7b for PKCS #7). Examples:

      Bash

      echo Q2VydGlmaWNhdGVEYXRh | base64 --decode -o bash.pfx

      OpenSSL

      echo Q2VydGlmaWNhdGVEYXRh | openssl enc -base64 -d -out OpenSSL.pfx

      Perl

      use MIME::Base64;

      print decode_base64("Q2VydGlmaWNhdGVEYXRh");

      PowerShell

      [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String("Q2VydGlmaWNhdGVEYXRh")) >> C:\myfolder.RS-SAMPLE\Desktop\PowerShell.pfx

      Python

      import base64

      base64.b64decode("Q2VydGlmaWNhdGVEYXRh")

      where Q2VydGlmaWNhdGVEYXRh is the CertificateData response value. Replace the output file extension to match the format you requested.

    • DER: application/x-x509-ca-cert
    • JKS: application/octet-stream
    • PKCS #7: application/x-pkcs7-certificates
    • PKCS #12: application/x-pkcs12

HTTP 202

When the certificate is not ready, this API call returns:

  • Stage -1 Status: Queued for renewal.
  • Stage: 0, Status: Not yet available.

HTTP 400

Returns an Error message for bad parameters, data, or syntax:

  • Certificate does not exist.

  • Failed to read certificate [CertificateDN] user permissions.

  • Permissions error. You do not have sufficient rights to retrieve the certificate [CertificateDN].

  • Permissions error. You do not have sufficient rights to retrieve the certificate [CertificateDN] private key.

  • Failed to look up private key. Error: Failed to look up private key vault ID. This is the API result you will receive when attempting to download a certificate and private key if the certificate was generated from a user-provided CSR and the private key is not stored in Trust Protection Foundation.

Example: Get the certificate

Request

POST https://tpp.venafi.example/vedsdk/certificates/Retrieve
Authorization:Bearer EXAMPLE-bearer-token
{
   "CertificateDN":"\\VED\\Policy\\retrieve-me.venafi.example",
   "Format":"Base64",
   "IncludeChain":true,
   "RootFirstOrder":true
}

Response

HTTP/1.1 200 OK
{  
   "CertificateData":"c3ViamVjdD1DTj1WZW5hZmkgRXhhbXBsZSBSb290I...",
   "Filename":"retrieve-me.venafi.example.pem",
   "Format":"Base64"
}

Example: Get the certificate as a PFX file with private key

Request

POST https://tpp.venafi.example/vedsdk/certificates/Retrieve
Authorization:Bearer EXAMPLE-bearer-token
{
   "CertificateDN":"\\VED\\Policy\\retrieve-me.venafi.example",
   "Format":"PKCS #12",
   "IncludePrivateKey":true,
   "Password":"EXAMPLE-password",
   "IncludeChain":true
}

Response

HTTP/1.1 200 OK
{
   "CertificateData":"MIIRCAIBAzCCEcIGCSqGSIb3DQEHAaCCEb...",
   "Filename":"retrieve-me.venafi.example.pfx",
   "Format":"PKCS #12"
}

To save the certificate as a usable PFX file, Base64-decode the CertificateData value and write it to a .pfx file. For example, using PowerShell:

$response = Invoke-RestMethod -Method Post -Uri "https://tpp.venafi.example/vedsdk/certificates/Retrieve" `
  -Headers @{ Authorization = "Bearer EXAMPLE-bearer-token" } `
  -ContentType "application/json" `
  -Body '{"CertificateDN":"\\VED\\Policy\\retrieve-me.venafi.example","Format":"PKCS #12","IncludePrivateKey":true,"Password":"EXAMPLE-password"}'

[System.IO.File]::WriteAllBytes("C:\certs\retrieve-me.pfx", [System.Convert]::FromBase64String($response.CertificateData))