OV/EV certificate immediate issuance

7 minute read

This workflow guide is only for OV/EV certificate orders. To use immediate certificate issuance for DV orders, see DV certificate immediate issuance.

When using the API to order certificates, too often time is spent just waiting for the certificate to be issued. By following the steps in this workflow guide, you’ll be able to take advantage of our immediate issuance feature, allowing you to get your certificate issued immediately and reduce your API calls.

Overview

In order to take advantage of immediate issuance, these prerequisites must be met:

Your account is configured to automatically approve certificate requests or skip the approval step.
Organization associated with the certificate is prevalidated.
All domains to be secured by the certificate are prevalidated.
The user associated with the API key used to submit the order has permission to approve certificate requests.

When all these prerequisites are met, DigiCert returns the issued certificate in the order response. If any prerequisite is not met, DigiCert cannot immediately issue the certificate.

Approval step settings

By default, your CertCentral account is configured for one-step certificate request approvals. For immediate certificate issuance to work, the approval step needs to be bypassed. This can be done in one of two ways:

Automatically approve certificate requests: Orders still go through the request process and appear in your requests list.
Skip approval step: Orders skip the approval step entirely and do not appear in the request list.

Because the above configuration changes are mutually exclusive, you’ll need to decide which one you want to make based on your specific integration and organizational needs.

Both configurations allow Administrators and Managers to bypass the approval step for OV certificate requests. However, to bypass the EV certificate approval step, the user linked to the API key being used must also be designated as an EV approver.

Configure settings

In your account, in the sidebar menu, click Settings > Preferences.
On the Division Preferences page, scroll down and click + Advanced Settings.
Under Certificate Requests, find the Approval Steps options.
To bypass the approval step, choose one of these approval step options:
- Select One step: certificate requests must be approved, then check Automatically approve certificate requests when the requester is also an approver.
- Select Skip approval step: remove the approval step from your certificate order processes.
When you are finished, click Save Settings.

After configuring the approval step, prevalidate the organization and domains on your certificate.0

If your organization and domains have already been prevalidated, you can skip to Submit your certificate order.

Prevalidate organization and domains

Add and validate your organization

To add an organization to your CertCentral account and submit it for validation, use the Create organization endpoint. This endpoint accepts parameters with details about the organization, the organization contact, and the validation types you want to submit the organization for. When the organization is created, DigiCert begins the validation process.

If you don’t know the intended use for the organization, you can create the organization without submitting it for validation by omitting the validations array from the request body. Later, when you are ready, use the [Submit organization for validation](https://dev.digicert.com/certcentral-apis/services-api/organizations/submit-for-validation.html} endpoint to submit the organization for prevalidation.

This example cURL request creates an organization and submits it to be validated for OV and EV TLS certificate issuance.

Create organization and submit for validation (cURL)

curl -X POST \
  https://www.digicert.com/services/v2/organization \
  --header 'Content-Type: application/json' \
  --header 'X-DC-DEVKEY: {{api_key}}' \
  --data-raw '{
    "name": "Example Organization, LLC",
    "assumed_name": "Example Organization",
    "country": "us",
    "address": "ABC Movers",
    "address2": "Floor 08",
    "city": "Springfield",
    "state": "Virginia",
    "zip": "22162",
    "telephone": "555-555-0100",
    "organization_contact": {
      "first_name": "Jane",
      "last_name": "Doe",
      "job_title": "Manager",
      "email": "jane.doe@example.com",
      "telephone": "555-555-0100",
      "telephone_extension": "736"
    },
    "validations": [
      {
        "type": "ov"
      },
      {
        "type": "ev",
        "verified_users": [
          {
            "id": 7286246
          },
          {
            "first_name": "John",
            "last_name": "Doe",
            "job_title": "Site Reliability Engineer",
            "telephone": "555-555-1001",
            "email": "john.doe@example.com"
          }
        ]
      }
    ]
}'

201 Created

{
  "id": 112236
}

The value of the id parameter in the response body is the ID of the newly added organization. You’ll use this value when you submit your certificate order request.

Add and validate a domain

Repeat this step for each domain to be secured by the certificate.

Now you’re ready to add your domain and submit it for validation. To prevalidate a domain, use the Add domain endpoint.

This example request body adds a domain, assigns it to an organization, and submits it for OV and EV certificate validation. It also specifies the DCV method you want to use to demonstrate control over the domain. For descriptions of the supported DCV methods and guidance on selecting a method, see DCV Methods.

Add domain (cURL)

curl -X POST \
  https://www.digicert.com/services/v2/domain \
  --header 'Content-Type: application/json' \
  --header 'X-DC-DEVKEY: {{api_key}}' \
  --data-raw '{
  "name": "example.com",
  "organization": {
    "id": 112233
  },
  "validations": [
    {
      "type": "ov"
    },
    {
      "type": "ev"
    }
  ],
  "dcv_method": "email"
}

201 Created

{
    "id": 123356,
    "validation_emails": {
        "name_scope": "example.com",
        "base_emails": [
            "postmaster@example.com",
            "administrator@example.com",
            "hostmaster@example.com",
            "admin@example.com",
            "webmaster@example.com"
        ]
    }
}

After submitting your domain for validation, you’ll need to complete the domain’s DCV before immediate issuance can occur. For information about supported DCV methods, see DCV Methods.

Submit your certificate order

All submit order endpoints support immediate certificate issuance (Order EV/OV SSL and Order Secure Site SSL.

This example request body sends a certificate request using the Order EV/OV SSL endpoint. Because all immediate issuance requirements have been met, the full certificate chain is returned in the response body.

When using the Skip approval step setting, include "skip_approval": true in the order request. See Best practices - Always include skip_approval parameter for more info.

If any of the prerequisites are missing, immediate issuance won’t happen, and your request will not return the full certificate chain.

Request body

{
  "certificate": {
    "common_name": "example.com",
    "dns_names": [
      "sub.example.com",
      "app.example.com"
    ],
    "csr": "<csr>",
    "server_platform": {
      "id": 45
    },
    "signature_hash": "sha256",
    "cert_validity": {
      "days": 199
    }
  },
  "order_validity": {
    "years": 1
  },
  "disable_renewal_notifications": true,
  "dcv_method": "email",
  "locale": "en",
  "payment_method": "balance",
  "skip_approval": true,
  "organization": {
    "id": 112233
  },
  "custom_fields": [
    {
      "metadata_id": 11,
      "value": "Invoice #00001"
    }
  ]
}

201 Created

{
  "id": 112339,
  "certificate_id": 132345,
  "domains": [
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "example.com"
    },
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "sub.example.com"
    },
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "app.example.com"
    }
  ],
  "certificate_chain": [
    {
      "subject_common_name": "example.com",
      "pem": "<pem_certificate>"
    },
    {
      "subject_common_name": "DigiCert SHA2 Secure Server CA",
      "pem": "<pem_certificate>"
    },
    {
      "subject_common_name": "DigiCert Global Root CA",
      "pem": "<pem_certificate>"
    }
  ]
}

What if DigiCert can’t immediately issue the certificate?

When using organization and domain prevalidation, DigiCert will not immediately issue your certificate if:

Prevalidation is incomplete for the organization or domains on the certificate order request.
It takes longer than expected to process the certificate request.

In both cases, DigiCert creates the order in a pending state. The API returns the standard response for created orders in a pending state, omitting the certificate_chain:

{ 
  "id": 112233, 
  "domains": [ 
    { 
      "id": 1469, 
      "name": "example.com", 
      "dns_name": "example.com" 
    }, 
    { 
      "id": 1469, 
      "name": "example.com", 
      "dns_name": "sub.example.com" 
    }, 
    { 
      "id": 1469, 
      "name": "example.com", 
      "dns_name": "app.example.com" 
    } 
  ], 
  "certificate_id": 113 
}

To prevent failures caused by issuance delays, design your integration to account for the possibility of a pending order response. When immediate issuance fails, use the Order validation status endpoint to check whether organization and domain validation is complete.

If validation is incomplete:

Finish validating the organization and domains to enable certificate issuance.

If validation is complete:

The certificate will be issued as soon as DigiCert finishes processing the order. Use one of these these methods to find out when the certificate is ready to download: