DigiCert ONE

DigiCert® ONE is a modern PKI platform that provides a scalable foundation for fast and flexible PKI deployments. The DigiCert ONE APIs provide a powerful interface for managing your certificates and devices, customizing and automating workflows, and integrating DigiCert ONE with your existing PKI management tools.

This documentation includes information about using APIs for the following DigiCert ONE services:

Getting started

Before you can use the DigiCert ONE APIs, you need:

  • DigiCert ONE account
  • DigiCert ONE API key
  • Ability to make REST API requests

Authentication

The DigiCert ONE APIs support header-based API key authentication. Additionally, a subset of the IoT Device Manager APIs support authentication using an enrollment passcode or client certificate.

API key authentication

To authenticate with an API key, include the custom HTTP header x‑api‑key in your request. Provide your own API key as the value for this header when you submit your request.

For example, here's a request to the endpoint for creating a new device:

bash
curl -X POST \
  'https://one.digicert.com/iot/api/v1/device' \
  -H 'x-api-key: {{api_key}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "division_id": {{division_id}},
    "device_identifier": "MyDevice",
    "device_profile_id": {{device_profile_id}}
  }'

Create an API key

To create a new API key:

  1. Sign in to your DigiCert ONE account.
  2. Navigate to the Account Manager console.
  3. From the left menu, select Access > Administrators.
  4. Find your information in the Administrators list, and select your name to open the Administrator details page.
  5. From the Administrator details page, in the API Tokens section, select Create API token.
  6. Fill out the form to create the key.
  7. Copy it. Remember to stash the API key in a safe location. Delete it when you no longer need it.

Each API key is only displayed once. There is no way to retrieve a lost API key. If you ever lose an API key, revoke it and generate a new one.

Enrollment passcode authentication

The following endpoints in the IoT Device Manager API support the option to authenticate with an enrollment passcode instead of an API key:

To authenticate with an enrollment passcode, use the custom HTTP header x-passcode. The value of the x-passcode header is the passcode associated with the enrollment profile you specify in the body of the request. Requests that use enrollment passcode authentication do not include the x-api-key header.

For example, here’s a call to the endpoint for requesting a new certificate:

bash
curl --request POST 'https://one.digicert.com/iot/api/v1/certificate' \
--header 'x-passcode: {{enrollment_passcode}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "csr": {{csr}},
  "enrollment_profile_id": {{enrollment_profile_id}},
  ...
}'

Client certificate authentication

Many endpoints in the IoT Device Manager API support the option for mutual TLS authentication. With mutual TLS authentication, a client can access the endpoint by presenting a trusted certificate in the request.

To use mutual TLS authentication:

  • Include a trusted certificate in your request.
  • In the base URL for the endpoint path, add the prefix clientauth.
    Example: https://clientauth.one.digicert.com
  • Omit the x-api-key header.

Supported endpoints

Clients can authenticate to the following endpoints by presenting a certificate associated with the device:

Clients can authenticate to the following endpoints by presenting a certificate that is registered to the enrollment profile specified in the request payload:

Base URL

Use this base URL to construct DigiCert ONE API requests:

generic
https://one.digicert.com

URL query strings

Some endpoints use URL query strings to filter results. To append query strings to the endpoint URL, use ?. To append additional query strings, use &.

This example uses the division_id query string to filter results to the specified division:

generic
https://one.digicert.com/iot/api/v1/device/{{device_identifier}}?division_id={{division_id}}

Requests

All requests are submitted via RESTful URLs using REST features, including header-based authentication and JSON request types.

The data character set encoding for requests is UTF-8. A well-formed request uses port 443 and specifies the user-agent and content-length HTTP headers.

Methods

The DigiCert ONE APIs use standard HTTP methods, including:

  • GET
  • POST
  • PUT
  • DELETE

Body

Unless otherwise noted, most requests require passing either JSON or XML formatted data. Supported values for the Content-Type header include:

  • application/json

Responses

Responses consist of headers and a body. The formatting of the response body depends on the content-type you specify in the request.

For more information about individual HTTP header response codes, see Glossary – Headers.