Skip to main content

OV/EV certificate immediate issuance

Notice

This workflow guide is only for OV/EV certificate orders. To used 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 by up to 70%.

Overview

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

  • Your account is configured to auto approve requests or skip the request process.

  • Organization associated with certificate is prevalidated.

  • All domains to be secured by the certificate are prevalidated.

  • API key used to submit the order has permissions to approve certificate requests.

When all of these prerequisites are met, your issued certificate is returned in the response body. If any of these prerequisites are missing, immediate issuance cannot happen.

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.

Notice

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

  1. In your account, in the sidebar menu, click Settings > Preferences.

  2. On the Division Preferences page, scroll down and click + Advanced Settings.

  3. Under Certificate Requests, find the Approval Steps options.

  4. 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.

  5. When you are finished, click Save Settings.

With the Auto Approve Request feature enabled, the next step is to prevalidate the organization and domains on your certificate.

Note

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.

Note

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're ready, submit the organization for prevalidation by using the Submit organization for validation endpoint.

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

Example 1. 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"
          }
        ]
      }
    ]
}'

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

Note

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.

Example 3. 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"
}'{
    "name": "example.com",
    "organization": {
        "id": 112233
    },
    "validations": [
        {
            "type": "ov"
        },
        {
            "type": "ev"
        }
    ],
    "dcv_method": "email"
}

Notice

After submitting your domain for validation, you'll need to complete the domain's DCV before immediate issuance can occur.

Submit your certificate order

All submit order endpoints support immediate certificate issuance (Order EV/OV SSL, Order Secure Site SSL, Order DV 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.

Important

When using the Skip approval step setting, make sure to include the skip_approval parameter with a value of true. See Best practices - Always include skip_approval parameter for more info.

Note

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

Example 5. Request body
{
  "certificate": {
    "common_name": "example.com",
    "dns_names": [
      "sub.example.com",
      "app.example.com"
    ],
    "csr": "<csr>",
    "server_platform": {
      "id": 45
    },
    "signature_hash": "sha256"
  },
  "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"
    }
  ]
}

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:

Then, when the order status becomes issued, download the certificate:

In this section: