Introduction

API Basics

All API requests are submitted via REST-based URLs using REST features including HEADER-based authentication and JSON/XML request types.

The requests will be accepted through port 443, which is the default port for SSL. The character set encoding of data in API calls and responses is UTF-8. To ensure a well-formed request, make sure that the User-Agent and Content-Length headers are specified in the request.

Authentication

The REST API requires access to the existing Digicert APIs and utilizes the same keys. However to authenticate with the service, it uses Basic HTTP Authentication over SSL.

As basic authentication is an established standard, it is easy to implement. Using cURL:

curl -u "account_id:api_key" ...

Building the header manually:

1. Combine the account id and api key into a string: account_id:api_key
2. Base64 encode the string
3. Add the encoded string to the header: Authorization: Basic {BASE64_ENCODED_STRING}

So this is also valid in cURL:

curl -H "Authorization: Basic {BASE64_ENCODED_STRING}"

Usage Guidelines

Rate limits are put in place to prevent abuse, and may be changed in the future without notice. If you exceed the per-hour or per-day limit or otherwise abuse the service, the DigiCert Rest API may stop working for you temporarily.

DigiCert will typically rate limit API usage at around 1000 hits per hour. If you require a higher API limit threshold, contact a member of the DigiCert sales team to see what options are available for your usage patterns.

Requests

Requests consist of two or three parts: Method, Endpoint, and Body. Every request has a method and endpoint, but some also include a body. The body is formatted based on the Content-Type header sent.

Method

The API uses four standard HTTP methods and several custom methods. The standard methods supported are GET, HEAD, OPTIONS, and POST. The custom methods are APPROVE, REISSUE, REJECT, RENEW, and REVOKE. The client can use any of these methods directly. This is the preferred method. To use with cURL:

curl -u "account_id:api_key" -X {CUSTOM_METHOD}...

So, to revoke a request:

curl -u "account_id:api_key" -X REVOKE ...

Some client libraries may not allow custom HTTP methods. For these libraries, there is an additional way to set the method for a request: use a custom HTTP header.

To use:

1. Set the HTTP method as POST.
2. Create a header named X-HTTP-Method-Override and set the value to be one of the custom methods.

To use with cURL:

curl -u "account_id:api_key" -X POST -H "X-HTTP-Method-Override: REVOKE"...

Endpoint

REST requests use endpoints to retrieve and alter data. Endpoints are generally split into two types:

1. Collection: Represents a group of items. Examples include /order where POST creates a new item and GET returns a list of items.
2. Item: Represents a single item. These endpoints usually have an id attached at the end of the URL. Examples include /order/00112233 where POST affects the particular order and GET returns details about the order.

Specific endpoints will be described later when explaining how to make specific requests.

Request Filters

Filters are appended to the end of a URL using a ?. Multiple filters can be applied to the same request. If using multiple filters, they are separated with a '&' character.

Body and Content Type

Most requests require passing in either JSON or XML formatted data. Some requests may require standard content types like image/jpeg. If an endpoint supports or requires a format other than JSON or XML, it will be noted in the documentation. Generally GET requests are the only ones that do not require sending formatted data. With some endpoints, GET requests will support passing in additional parameters to filter the results.

For requests that require additional data, instead of using the generic application/json and application/xml content types, the API supports custom content types that also include a version number.

The following content types are currently supported:

1. application/vnd.digicert.rest-v1+xml
2. application/vnd.digicert.rest-v1+json

To use, create a header:

A full cURL request may be something like:

curl -u "account_id:api_key" -X POST \
-H "Content-Type: application/vnd.digicert.rest-v1+json" \
--data '{"foo":"bar"}' https://api.digicert.com/fez/00112233

Responses

Responses consist of two parts: Headers and Body. The body is formatted based on the content type requested in the Accept header.

Headers

Every response will include an appropriate HTTP header. This header is based off of the RFC 2616 specification.

For most of the GET requests, the API will also return an Etag header so that clients can also pass in an If-None-Match header.

Body and Content Type

For simplicity, the API support the same content types for both responses and requests.

For GET requests, the client does not send additional data to the API. For these requests, it is more appropriate to send an Accept header than a Content-Type header. However, if a Content-Type header is passed and not an Accept header (or the header is Accept: */*), the API will default to using the value set in the Content-Type.

For other requests, a client only needs to send an Accept header if the request is sent in one format and the response should be sent in a different one (i.e. the request is a JSON-encoded string, but the response needs to be in XML).

If the API cannot determine which format the client wants, it will return a 406 header.

Successful Response

All success responses will return an HTTP code in the 200 – 399 range. Clients receiving these headers will know that their request was successfully handled and will expect an appropriate response.

As an example, a client submits a POST request to the /enterprise/certificate/ssl endpoint. It will expect a request_id that could used in subsequent Approval Requests. It would expect a response similar to below:

{
  "request_id":7902
}

<response>
  <request_id>7902</request_id>
</response>

Error Response

Error responses will return an HTTP code in 400+ range. Clients receiving these headers know that their request failed for various reasons. The API should always at least return a 500 error if there was a fatal error that wasn't caught. Most error responses return a special content type, based on the initial type being requested: application/vnd.digicert.error+xml for XML based requests, and application/vnd.digicert.error+json for JSON based. This content type is based on emerging standards.

For instance, a client wants to reject a pending request, but forgot to include the required NOTE. They would make a REJECT request to the /request/7902 endpoint, and would receive a 400 response with the following body:

{
  "errors":[
    {
      "code":"required_param:note",
      "description":"Note is required"
    }
  ]
}

<errors>
  <error>
    <code>required_param:note</code>
    <description>Note is required</description>
  </error>
</errors>

Endpoint Overview

HEAD Requests

Any endpoint that supports a GET method also supports the HEAD method. As defined by RFC 2616, a HEAD request is treated the same as a GET request, except that it doesn't contain a response body.

OPTIONS Requests

All endpoints support an OPTIONS method call. The OPTIONS method as defined in RFC 2616 returns the same ALLOW header as a 405 error response.