Skip to main content

Overview

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:

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.

Danger

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 operations in the IoT Device Manager API support the option to authenticate with an enrollment passcode instead of an API key:

  • Request certificate

  • Renew certificate

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:

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 operations by presenting a certificate associated with the device:

  • Get device details by ID (client authentication)

  • Update device by ID (client authentication)

  • Renew device certificate by device ID (client authentication)

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

  • Request certificate

  • Renew certificate

Base URL

Use this base URL to construct DigiCert ONE API requests:

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:

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.