Request a TLS certificate

13 minute read

Automating TLS certificate issuance reduces manual effort, accelerates deployment cycles, and ensures consistent security posture across your infrastructure. This tutorial walks you through the complete certificate request workflow using DigiCert® Trust Lifecycle Manager API.

What you’ll learn

In this tutorial, you will:

Retrieve available certificate profiles from your account.
Generate a certificate signing request (CSR).
Submit a certificate request and receive the issued certificate
Verify certificate status and retrieve it in different formats.
Troubleshoot common errors during the certificate request process.

Before you begin

Before starting this tutorial, make sure you have:

Completed or understand Making your first API call.

A service user with the EM_EPKI_USER_&_CERT_MANAGER role assigned. This role includes the Manage create permission required to enroll certificates. (Use /account/api/v1/user/me to verify assigned roles).

A certificate profile with enrollment_method set to rest_api.

OpenSSL installed on your system (use openssl version to verify).

If using curl, jq should be installed (jq --version).

Endpoint overview

The following endpoints are used in this tutorial.

Primary endpoints

Purpose	Method	Endpoint
Retrieve certificate profiles	`GET`	`/mpki/api/v2/profile`
Submit certificate request	`POST`	`/mpki/api/v1/certificate`
Check certificate status	`GET`	`/mpki/api/v1/certificate/{serial_number}`
Get additional certificate formats	`GET`	`/mpki/api/v1/certificate/{serial_number}/additional-formats`

Supporting endpoints

Purpose	Method	Endpoint
Certificate pickup (Microsoft CA templates)	`POST`	`/mpki/api/v1/certificate-pickup/{request_id}`

Step 1: List available certificate profiles

Certificate profiles define the characteristics of the certificates you’ll issue, such as certificate type, validity period, key parameters, and enrollment methods. Before you can request a certificate, you need to identify which profile matches your requirements.

You can retrieve all available profiles in your account using the /mpki/api/v2/profile endpoint. The limit parameter controls how many profiles are returned per response (default: 20), and you can use offset for pagination if you have many profiles.

Important

If you’re using Public S/MIME Secure Email (DigiCert CertCentral®-based) templates, use the /api/v2 version of this endpoint for proper compatibility.

curl -X GET "https://demo.one.digicert.com/mpki/api/v2/profile?offset=0&limit=20" \
  -H "x-api-key: SERVICE_API_TOKEN" \
  -H "Content-Type: application/json" | jq '.'

import requests

# Configuration
BASE_URL = "https://demo.one.digicert.com"
SERVICE_API_TOKEN = "SERVICE_API_TOKEN"
OFFSET = 0
LIMIT = 20

# Get certificate profiles
response = requests.get(
    f"{BASE_URL}/mpki/api/v2/profile",
    headers={
        "x-api-key": SERVICE_API_TOKEN,
        "Content-Type": "application/json"
    },
    params={
        "offset": OFFSET,
        "limit": LIMIT
    }
)

print(f"Status Code: {response.status_code}")
print(response.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        // Configuration
        String baseUrl = "https://demo.one.digicert.com";
        String serviceApiToken = "SERVICE_API_TOKEN";
        int offset = 0;
        int limit = 20;

        // Get certificate profiles
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/mpki/api/v2/profile?offset=" + offset + "&limit=" + limit))
            .header("x-api-key", serviceApiToken)
            .header("Content-Type", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        System.out.println("Status Code: " + response.statusCode());
        System.out.println(response.body());
    }
}

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        // Configuration
        string baseUrl = "https://demo.one.digicert.com";
        string serviceApiToken = "SERVICE_API_TOKEN";
        int offset = 0;
        int limit = 20;

        // Get certificate profiles
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("x-api-key", serviceApiToken);
        client.DefaultRequestHeaders.Add("Content-Type", "application/json");

        var response = await client.GetAsync(
            $"{baseUrl}/mpki/api/v2/profile?offset={offset}&limit={limit}"
        );

        string responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine($"Status Code: {(int)response.StatusCode}");
        Console.WriteLine(responseBody);
    }
}

Successful response:

[
    {
      "id": "d6743d9a-fb67-4a64-a33e-8a3229d28cc4",
      "name": "Profile name",
      "status": "Active",
      "signature_algorithm": "SHA256_WITH_RSA",
      "publish_to_public_directory": false,
      "renewal_period_days": 30,
      "duplicate_cert_policy": false,
      "override_cert_validity_via_api": true,
      "certificate_delivery_format": "pkcs7",
      "account_id": "3ff33f88-5717-4542-b3fc-3f312f44afa4",
      "business_unit_id": "e5bf49f0-a77b-4301-85e9-c15eb12df70f",
      "enrollment_method": "rest_api",
      "authentication_method": "third_party_app",
      "days_till_enrollment_expires": 10,
      "automated_renewal": true,
      "renewal_window_days": 30,
      "custom_extended_key_usages": [
        "1.2.840.113583.1.1.7"
      ],
      "private_key_attributes": {
        "key_size": "2048"
      },
      "key_escrow_policy": {
        "key_escrow_enabled": true,
        "key_escrow_deployment_mode": "CLOUD",
        "dual_admin_recovery": true
      },
      "api_token_binding_enabled": true,
      "api_token_ids": [
        "8517a493-ef6a-405e-85f1-eecd538e7692",
        "8517a493-ef6a-405e-85f1-eecd538e7693"
      ],
      "enable_dual_admin_approval": true,
      "certificate": {
        "subject": {
          "attributes": [
            {
              "type": "common_name",
              "mandatory": true,
              "multiple": false,
              "sources": [
                {
                  "mandatory": true,
                  "source": "ENTERED_BY_USER_DURING_ENROLLMENT",
                  "ad_attribute_key": "cn"
                }
              ]
            },
            {
              "type": "domain_component",
              "mandatory": true
            },
            {
              "type": "organization_name",
              "mandatory": true,
              "multiple": false,
              "source": [
                {
                  "mandatory": false,
                  "source": "UPLOADED_BY_ADMIN"
                }
              ]
            },
            {
              "type": "street_address",
              "mandatory": true,
              "multiple": false,
              "source": [
                {
                  "mandatory": false,
                  "source": "AD_ATTRIBUTE",
                  "ad_attribute_key": "streetAddress"
                },
                {
                  "mandatory": true,
                  "source": "FIXED_VALUE",
                  "value": "20 Cooper Square"
                }
              ]
            },
            {
              "type": "country",
              "mandatory": true
            },
            {
              "type": "locality",
              "mandatory": true
            },
            {
              "type": "state",
              "mandatory": true
            },
            {
              "type": "postal_code",
              "mandatory": true
            }
          ]
        },
        "validity": {
          "unit": "days",
          "duration": 365
        },
        "extensions": {
          "san": {
            "critical": false,
            "attributes": [
              {
                "type": "emails",
                "mandatory": true,
                "multiple": false,
                "sources": [
                  {
                    "mandatory": true,
                    "source": "entered_by_user_during_enrollment"
                  }
                ]
              },
              {
                "type": "user_principal_names",
                "mandatory": false,
                "multiple": false,
                "sources": [
                  {
                    "mandatory": false,
                    "source": "uploaded_by_admin"
                  }
                ]
              }
            ]
          },
          "security_identifier": {
            "attributes": [
              {
                "type": "critical",
                "mandatory": false,
                "multiple": false,
                "sources": [
                  {
                    "mandatory": false,
                    "source": "entered_by_user_during_enrollment"
                  }
                ]
              },
              {
                "type": "additional_values",
                "mandatory": false,
                "multiple": false,
                "sources": [
                  {
                    "mandatory": false,
                    "source": "entered_by_user_during_enrollment"
                  }
                ]
              }
            ]
          }
        },
        "issuer": {
          "serial_number": "254554466396905590377942608199604315083804010285",
          "subject_dn": "CN=USCSS Nostromo, O=Weyland-Yutani, C=US",
          "certificate": "-----BEGIN CERTIFICATE-----\n•••\n•••\n•••\n-----END CERTIFICATE-----\n",
          "root": false,
          "chain": [
            {
              "serial_number": "254554466396905590377942608199604315083804010285",
              "subject_dn": "CN=The Company, O=Weyland-Yutani, C=US",
              "certificate": "-----BEGIN CERTIFICATE-----\n•••\n•••\n•••\n-----END CERTIFICATE-----\n",
              "root": true
            }
          ]
        }
      },
      "enable_ldap_search": false,
      "useCustomContact": false,
      "cert_delivery_format": "x509",
      "template": {
        "id": "99bfc12d-6732-e6c6-3f6d-a8c30e7833c1",
        "name": "Domain Controller",
        "trust_type": "private"
      },
      "connector_id": "914bfbc2-b2e2-11ef-a370-fe7b3e6ed6dd",
      "fields": {
        "optional": false,
        "multiple": false,
        "key": "subject_common_name",
        "type": "string",
        "input": "text",
        "sources": {
          "source": "entered_by_user_during_enrollment",
          "optional": false,
          "multi_value": false,
          "labels": []
        },
        "labels": [],
        "max": 64,
        "default_value": null
      },
      "business_unit": {
        "id": "e5bf49f0-a77b-4301-85e9-c15eb12df70f",
        "name": "Test BU"
      },
      "account": {
        "id": "3ff33f88-5717-4542-b3fc-3f312f44afa4"
      }
    }
]

From the returned list of profiles, identify the profile you want to use and save its id value. You’ll need this when submitting your certificate request in Step 3. Pay attention to the enrollment_method field. It must be set to rest_api for API-based certificate requests.

Step 2: Generate a certificate signing request (CSR)

Before submitting a certificate request, generate a private key and CSR. The CSR contains the public key and subject information for your certificate.

Important

Keep your private key secure and never share it. An exposed private key allows attackers to decrypt traffic and forge your identity.

Generate the private key and CSR

# Generate a 2048-bit RSA private key
openssl genrsa -out private.key 2048

# Generate the CSR
openssl req -new -key private.key -out request.csr \
  -subj "/C=US/ST=Utah/L=Lehi/O=DigiCert Inc/CN=example.com"

# Secure the private.key file
chmod 400 private.key

# Verify the CSR (optional)
openssl req -in request.csr -noout -text

Understanding CSR subject fields

Your CSR must include the subject fields required by your certificate profile. The most common fields include:

CN (Common Name): The fully qualified domain name for your certificate.
O (Organization): Your legal organization name
OU (Organizational Unit): Department or division within your organization (optional)
L (Locality): City name
ST (State): State or province name
C (Country): Two-letter ISO country code

Note

Subject field requirements vary by certificate profile configuration. Review your profile details from Step 1 to determine which fields are mandatory.

Step 3: Submit certificate request

With your CSR generated, you’re ready to submit your certificate request. The /mpki/api/v1/certificate endpoint requires three essential pieces of information:

profile.id: The certificate profile ID from Step 1
profile.seat.id: The identifier for the seat (typically an email address) that will own this certificate
profile.csr: The CSR content you generated in Step 2

Note

For certificate profiles configured with immediate issuance, the endpoint returns the signed certificate directly in the response. Profiles requiring approval or using Microsoft CA templates return a request_id instead, which you’ll use to retrieve the certificate once it’s been issued.

curl -X POST "https://demo.one.digicert.com/mpki/api/v1/certificate" \
  -H "x-api-key: SERVICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "id": "PROFILE_ID",
      "seat": {"id": "user@example.com"},
      "csr": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",
      "attributes": {
        "subject": {
          "common_name": "example.com"
        }
      }
    }
  }'

import requests

# Configuration
BASE_URL = "https://demo.one.digicert.com"
SERVICE_API_TOKEN = "SERVICE_API_TOKEN"
PROFILE_ID = "PROFILE_ID"
SEAT_ID = "user@example.com"
CSR = "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----"
COMMON_NAME = "example.com"

# Issue certificate
payload = {
    "profile": {
        "id": PROFILE_ID,
        "seat": {"id": SEAT_ID},
        "csr": CSR,
        "attributes": {
            "subject": {
                "common_name": COMMON_NAME
            }
        }
    }
}

response = requests.post(
    f"{BASE_URL}/mpki/api/v1/certificate",
    headers={
        "x-api-key": SERVICE_API_TOKEN,
        "Content-Type": "application/json"
    },
    json=payload
)

print(f"Status Code: {response.status_code}")
print(response.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;

public class Example {
    public static void main(String[] args) throws Exception {
        // Configuration
        String baseUrl = "https://demo.one.digicert.com";
        String serviceApiToken = "SERVICE_API_TOKEN";
        String profileId = "PROFILE_ID";
        String seatId = "user@example.com";
        String csr = "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----";
        String commonName = "example.com";

        // Build JSON payload
        ObjectMapper mapper = new ObjectMapper();
        ObjectNode payload = mapper.createObjectNode();
        ObjectNode profile = mapper.createObjectNode();
        profile.put("id", profileId);

        ObjectNode seat = mapper.createObjectNode();
        seat.put("id", seatId);
        profile.set("seat", seat);

        profile.put("csr", csr);

        ObjectNode attributes = mapper.createObjectNode();
        ObjectNode subject = mapper.createObjectNode();
        subject.put("common_name", commonName);
        attributes.set("subject", subject);
        profile.set("attributes", attributes);

        payload.set("profile", profile);

        // Issue certificate
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/mpki/api/v1/certificate"))
            .header("x-api-key", serviceApiToken)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(payload)))
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        System.out.println("Status Code: " + response.statusCode());
        System.out.println(response.body());
    }
}

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        // Configuration
        string baseUrl = "https://demo.one.digicert.com";
        string serviceApiToken = "SERVICE_API_TOKEN";
        string profileId = "PROFILE_ID";
        string seatId = "user@example.com";
        string csr = "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----";
        string commonName = "example.com";

        // Build JSON payload
        var payload = new JsonObject
        {
            ["profile"] = new JsonObject
            {
                ["id"] = profileId,
                ["seat"] = new JsonObject { ["id"] = seatId },
                ["csr"] = csr,
                ["attributes"] = new JsonObject
                {
                    ["subject"] = new JsonObject
                    {
                        ["common_name"] = commonName
                    }
                }
            }
        };

        // Issue certificate
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("x-api-key", serviceApiToken);

        var content = new StringContent(
            payload.ToJsonString(),
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync(
            $"{baseUrl}/mpki/api/v1/certificate",
            content
        );

        string responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine($"Status Code: {(int)response.StatusCode}");
        Console.WriteLine(responseBody);
    }
}

Successful response:

{
  "serial_number": "4099ABF9C1BB7C02BBE1CDC7836CA9D58A71C2A5",
  "delivery_format": "x509",
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

Save the serial_number. You need it to check the request status or retrieve the certificate later. For profiles with immediate issuance, you can extract and use the certificate in PEM format directly from the certificate field.

Note

If the response includes a request_id instead of a certificate, the profile requires manual approval or delayed processing. Use the /mpki/api/v1/certificate-pickup/{request_id} endpoint to retrieve the certificate once it becomes available.

Step 4: Check certificate status

After submitting your certificate request, you can verify the issuance status and retrieve detailed certificate information using the serial number returned in Step 3. This endpoint is also useful for tracking certificate lifecycle events, confirming successful issuance, or troubleshooting requests that require manual approval.

curl -X GET "https://demo.one.digicert.com/mpki/api/v1/certificate/SERIAL_NUMBER/additional-formats" \
  -H "x-api-key: SERVICE_API_TOKEN" \
  -H "Content-Type: application/json" | jq '.'

import requests

# Configuration
BASE_URL = "https://demo.one.digicert.com"
SERVICE_API_TOKEN = "SERVICE_API_TOKEN"
SERIAL_NUMBER = "SERIAL_NUMBER"

# Get additional certificate formats
response = requests.get(
    f"{BASE_URL}/mpki/api/v1/certificate/{SERIAL_NUMBER}/additional-formats",
    headers={
        "x-api-key": SERVICE_API_TOKEN,
        "Content-Type": "application/json"
    }
)

print(f"Status Code: {response.status_code}")
print(response.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        // Configuration
        String baseUrl = "https://demo.one.digicert.com";
        String serviceApiToken = "SERVICE_API_TOKEN";
        String serialNumber = "SERIAL_NUMBER";

        // Get additional certificate formats
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/mpki/api/v1/certificate/" + serialNumber + "/additional-formats"))
            .header("x-api-key", serviceApiToken)
            .header("Content-Type", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        System.out.println("Status Code: " + response.statusCode());
        System.out.println(response.body());
    }
}

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        // Configuration
        string baseUrl = "https://demo.one.digicert.com";
        string serviceApiToken = "SERVICE_API_TOKEN";
        string serialNumber = "SERIAL_NUMBER";

        // Get additional certificate formats
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("x-api-key", serviceApiToken);
        client.DefaultRequestHeaders.Add("Content-Type", "application/json");

        var response = await client.GetAsync(
            $"{baseUrl}/mpki/api/v1/certificate/{serialNumber}/additional-formats"
        );

        string responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine($"Status Code: {(int)response.StatusCode}");
        Console.WriteLine(responseBody);
    }
}

Successful response:

{
  "profile": {
    "id": "7f606454-e011-4cfb-af90-5a13232bbd8f",
    "name": "Example Certificate Profile"
  },
  "seat": {
    "seat_id": "some-seat-id@example.com"
  },
  "business_unit": {
    "id": "12d3c45e-d3e6-46fc-7f48-91030fa5cac6",
    "name": "Example-BU1"
  },
  "account": {
    "id": "f3f99122-1234-567a-919b-5f692216ff85"
  },
  "certificate": "...(Base64-encoded certificate)...",
  "ica": {
    "id": "444FFF3A03C12BCEF463B5D2EF01985F"
  },
  "common_name": "host1.example.com",
  "status": "issued",
  "serial_number": "0F6F55555658A989F0F463A4DA0D807F",
  "thumbprint": "FE0EFDC64AA55565556152850D2B84B46EF433444A28970F6A2A7F510A7A8880",
  "valid_from": "<YYYY-MM-DD>T<HH:MM:SS>Z",
  "valid_to": "<YYYY-MM-DD>T<HH:MM:SS>Z",
  "notes": "Some example notes about the valid certificate",
  "template_name": "Template Name",
  "issuing_ca_name": "Issuing CA Name",
  "key_size": 2048,
  "signature_algorithm": "RSA",
  "subject": {
    "common_name": "host1.example.com",
    "organization_name": "Example Org",
    "organization_units": "Example Org Unit",
    "description": "Some example description",
    "serial_number": "0F6F55555658A989F0F463A4DA0D807F",
    "pseudonym": "Some example pseudonym",
    "unique_identifier": "3a3aeb976040eed5c5d3bfb6143b7814",
    "user_identifier": "Some example user identifier",
    "domain_component": "Some example domain component",
    "dn_qualifier": "Some example DN qualifier",
    "unstructured_name": "Some example unstructured name",
    "unstructured_address": "Some example unstructured address",
    "street_address": "Some example street address",
    "postal_code": 89714,
    "locality": "Carson city",
    "state": "NV",
    "country": "US",
    "email": "some@mail",
    "title": "Some example title",
    "given_name": "Some example given name",
    "surname": "Some example surname",
    "organization_identifier": "1.3.6.1.4.1.311.60.2.1.3"
  },
  "cert_security_rating": "Secure",
  "security_rating_info": {
    "security_rating": {
      "encryption": [
        {
          "category_name": "Encryption",
          "criteria_name": "AES256",
          "value": "Strong",
          "rating": {
            "value": true,
            "issue": "None"
          },
          "data": {
            "key_size": 256,
            "mode": "CBC"
          }
        }
      ]
    },
    "handshake_protocols": [
      {
        "cipher_algorithm": "ECDHE-RSA-AES256-GCM-SHA384",
        "key_size": 256,
        "protocol": "TLSv1.2"
      }
    ],
    "security_headers": {
      "X-Content-Type-Options": "nosniff"
    },
    "http_response_headers": {
      "Content-Security-Policy": "default-src 'self'"
    },
    "certificate_chain": {
      "cert_chain_details": [
        {
          "cert_chain_id": 1,
          "overall_status": "Valid",
          "is_additional_cert_chain": false,
          "is_valid_chain": true,
          "cert_details": [
            {
              "status": "Active",
              "expiration_date": 1672531199000,
              "key_algorithm": "RSA",
              "algorithm_type": "SHA256",
              "issue_date": 1609459200000,
              "issuer_DN": "CN=Example CA, O=Example Inc., C=US",
              "subject": "CN=example.com, O=Example Inc., C=US",
              "errors": []
            }
          ]
        }
      ]
    },
    "security_rating_score": "Secure",
    "certificate_chain_score": "Secure",
    "handshake_protocol_score": [
      "Secure"
    ],
    "security_headers_score": "Secure",
    "http_response_headers_score": 10,
    "protocol_ciphers": [
      {
        "protocol": "TLSv1.2",
        "insecure_iphers": [
          {
            "code": 1,
            "forward_secrecy": false,
            "kex_info": "RSA",
            "name": "RC4",
            "unsafe": 1
          }
        ],
        "weak_ciphers": [],
        "safe_ciphers": [
          {
            "code": 156,
            "forward_secrecy": true,
            "kex_info": "ECDHE-RSA",
            "name": "AES256-GCM-SHA384",
            "unsafe": 0
          }
        ],
        "compressors": "DEFLATE",
        "cipher_pref_order": "client",
        "warnings": ""
      }
    ],
    "protocol_cipher_score": {
      "protocols": [
        "TLSv1.2",
        "TLSv1.3"
      ],
      "score": "Secure"
    }
  }
}

The response provides comprehensive certificate details, including profile information, validity periods, and security ratings. Key fields to review:

status: Current certificate state (issued, pending, revoked)
valid_from / valid_to: Certificate validity period
certificate: The PEM-encoded certificate (if issued)
thumbprint: Certificate fingerprint for verification
cert_security_rating: Overall security assessment

If the status field shows issued, your certificate is ready to use. For other status values like pending, the certificate may be awaiting approval or additional processing.

Step 5: Download additional certificate formats

The initial certificate issuance returns your certificate in X.509 (PEM) format. For deployments requiring bundled certificate chains or alternative formats, retrieve additional options using the certificate’s serial number.

curl -X GET "https://demo.one.digicert.com/mpki/api/v1/certificate/SERIAL_NUMBER/additional-formats" \
  -H "x-api-key: SERVICE_API_TOKEN" \
  -H "Content-Type: application/json" | jq '.'

import requests

# Configuration
BASE_URL = "https://demo.one.digicert.com"
SERVICE_API_TOKEN = "SERVICE_API_TOKEN"
SERIAL_NUMBER = "SERIAL_NUMBER"

# Get additional certificate formats
response = requests.get(
    f"{BASE_URL}/mpki/api/v1/certificate/{SERIAL_NUMBER}/additional-formats",
    headers={
        "x-api-key": SERVICE_API_TOKEN,
        "Content-Type": "application/json"
    }
)

print(f"Status Code: {response.status_code}")
print(response.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        // Configuration
        String baseUrl = "https://demo.one.digicert.com";
        String serviceApiToken = "SERVICE_API_TOKEN";
        String serialNumber = "SERIAL_NUMBER";

        // Get additional certificate formats
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/mpki/api/v1/certificate/" + serialNumber + "/additional-formats"))
            .header("x-api-key", serviceApiToken)
            .header("Content-Type", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        System.out.println("Status Code: " + response.statusCode());
        System.out.println(response.body());
    }
}

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        // Configuration
        string baseUrl = "https://demo.one.digicert.com";
        string serviceApiToken = "SERVICE_API_TOKEN";
        string serialNumber = "SERIAL_NUMBER";

        // Get additional certificate formats
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("x-api-key", serviceApiToken);
        client.DefaultRequestHeaders.Add("Content-Type", "application/json");

        var response = await client.GetAsync(
            $"{baseUrl}/mpki/api/v1/certificate/{serialNumber}/additional-formats"
        );

        string responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine($"Status Code: {(int)response.StatusCode}");
        Console.WriteLine(responseBody);
    }
}

Successful response:

{
  "pkcs7": "-----BEGIN PKCS7-----\n...\n-----END PKCS7-----",
  "x509_cert_chain": [
    {
      "common_name": "example.com",
      "cert_blob": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
    },
    {
      "common_name": "Intermediate CA",
      "cert_blob": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
    },
    {
      "common_name": "Root CA",
      "cert_blob": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
    }
  ]
}

The response provides your certificate and chain in two formats:

pkcs7: Certificate and complete trust chain bundled in PKCS#7 format
x509_cert_chain: Array containing your certificate and all chain certificates as individual PEM-encoded entries, ordered from end-entity certificate to root CA

Each certificate in the x509_cert_chain array includes the certificate’s common_name and the PEM-encoded certificate in cert_blob.

Common errors and solutions

{
    "errors": [
        {
            "code": "AUTHORIZATION_ERROR",
            "message": "No authentication data provided"
        }
    ]
}

Make sure you include a valid API token with your request using the `x-api-key` header.

{
    "errors": [
        {
            "code": "no_access",
            "message": "Not enough permissions"
        }
    ]
}

Make sure your API token has appropriate roles and permissions.

{
    "errors": [
        {
            "code": "invalid_input_field",
            "message": "Wrong input or input format"
        }
    ]
}

Check endpoint specifications for valid field values.

Check your request body and validate your JSON.

{
    "errors": [
        {
            "code": "duplicate_error",
            "message": "Nickname [name] already exists. Enter a different nickname."
        }
    ]
}

Use a different value for the specified field.

Was this page helpful?

Provide feedback

Need more help?

Account and platform

Certificates and PKI

Signing

Devices and IoT

Other resources

Request a TLS certificate

What you’ll learn

Before you begin

Endpoint overview

Step 1: List available certificate profiles

Important

Step 2: Generate a certificate signing request (CSR)

Important

Understanding CSR subject fields

Note

Step 3: Submit certificate request

Note

Note

Step 4: Check certificate status

Step 5: Download additional certificate formats

Common errors and solutions