GET Certificates/Retrieve

Returns the available certificate data and optional private key information for an enrolled certificate. The requested certificate returns, with the appropriate mime-type and content‑disposition to allow HTTP clients to properly save the file.

This API method matches POST Certificates/Retrieve, except that all arguments are passed as part of the URL.

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.

Because this is a GET request, special characters in the format value must be URL-encoded. For example, use PKCS+%2312 or PKCS%20%2312 for PKCS #12.

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

(Optional) 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 #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: The root certificate first, followed by intermediate certificates, and finally the end entity certificate.
  • false: Default. 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

For valid requests, GET Certificates/Retrieve returns a HTTP 200 message and certificates based on the Format in the request. 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.

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

For invalid requests, the method fails to return the certificate data and optional private key information. Certificates/Retrieve returns a HTTP 400 BadRequest and Error for missing parameters or one of the following errors:

  • 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 an existing certificate and list the Root certificate first

Request

GET https://tpp.venafi.example/vedsdk/Certificates/Retrieve?CertificateDN=%5CVED%5CPolicy%5Cretrieve-me.venafi.example&Format=Base64&IncludeChain=true&RootFirstOrder=true
Authorization:Bearer EXAMPLE-bearer-token

Response

HTTP/1.1 200 OK

Content-Disposition: attachment; filename="retrieve-me.venafi.example.pem"
Content-Length: 5966
Content-Type: application/x-pem-file

-----BEGIN CERTIFICATE-----
MIIE9aFFA8kgAwIBHgIHAKvN8x ...
-----END CERTIFICATE-----subject=CN=Venafi Example Root CA, OU=Demonstration Purposes, O="Venafi, Inc.", L=Salt Lake City, S=Utah, C=US
issuer=CN=Venafi Example Root CA, OU=Demonstration Purposes, O="Venafi, Inc.", L=Salt Lake City, S=Utah, C=US
-----BEGIN CERTIFICATE-----
MIIEmDCCA4CgAwIBAgIJALgpHD ...
-----END CERTIFICATE-----
subject=CN=Venafi Example Issuing CA, OU=Demonstration Services, O="Venafi, Inc.", L=Salt Lake City, S=Utah, C=US
issuer=CN=Venafi Example Root CA, OU=Demonstration Purposes, O="Venafi, Inc.", L=Salt Lake City, S=Utah, C=US
-----BEGIN CERTIFICATE-----
MIIE4zCCA8ugAwIBAgIHAKvN7w ...
-----END CERTIFICATE-----	
subject=CN=retrieve-me.venafi.example, OU=Quality Assurance, O="Venafi, Inc.", L=Salt Lake City, S=Utah, C=US
issuer=CN=Venafi Example Issuing CA, OU=Demonstration Services, O="Venafi, Inc.", L=Salt Lake City, S=Utah, C=US
-----BEGIN CERTIFICATE-----
MIIE+zCCA+OgAwIBAgIKYX5M+QA ...
-----END CERTIFICATE-----

Example: Download a PFX file with private key

Request

GET https://tpp.venafi.example/vedsdk/Certificates/Retrieve?CertificateDN=%5CVED%5CPolicy%5Cretrieve-me.venafi.example&Format=PKCS+%2312&IncludePrivateKey=true&Password=EXAMPLE-password&IncludeChain=true
Authorization:Bearer EXAMPLE-bearer-token

Response

HTTP/1.1 200 OK

Content-Disposition: attachment; filename="retrieve-me.venafi.example.pfx"
Content-Length: 4218
Content-Type: application/x-pkcs12

(binary PFX data)

The response body contains the raw PFX binary. HTTP clients such as curl can save the file directly. For example:

curl -H "Authorization: Bearer EXAMPLE-bearer-token" \
  -o retrieve-me.pfx \
  "https://tpp.venafi.example/vedsdk/Certificates/Retrieve?CertificateDN=%5CVED%5CPolicy%5Cretrieve-me.venafi.example&Format=PKCS+%2312&IncludePrivateKey=true&Password=EXAMPLE-password"