Authentication

DigiCert® ONE API integrations rely on service users. Service users are non-interactive identities created specifically for making API calls.

You can authenticate a service user using two primary methods:

Table 1. Primary authentication methods

Method	Best for	How it works
API key (default)	CI/CD jobs, backend services	Add the key for your service user in the `x-api-key` request header.
Mutual TLS (mTLS)	High-assurance, network-restricted, or key-rotation-averse environments	Present a client TLS certificate and call the `clientauth.` hostname.

Tip

Using Document Trust Manager? OAuth and digest flows are limited to CSC operations in Document Trust Manager. For all core product APIs, API keys and mTLS are the only options.

What is a service user?

A service user is essentially a credential container. Think of it as a headless account holding only the permissions your integration needs. Service users:

Authenticate using API keys or client certificates.
Cannot sign in to the user interface.
Are created in Account Manager (through browser or API).

Important

An API key is generated only when creating a new service user. You cannot regenerate an API key for an existing service user. Securely store your API key immediately after creation.

Create a service user (UI)

Note

To create a service user in DigiCert ONE, you must have a user role with Manage users permission.

Sign in to DigiCert ONE.
In the Manager menu (grid at top right), select Account.
In the Account menu, select Access > Service users.
Select Create service user.
Enter service user details:
1. Friendly name
  Enter a unique display name. The name must include only letters, numbers, spaces, dashes, and underscores. Actions are logged under this name.
2. Optional: Description
  Add additional information about the service user. This description only appears in the Service user details.
3. Optional: End date
  Specify an expiration date (UTC). For example, selecting January 12, 2026 means the service user expires at 23:59:59 UTC.
  Tip
  Update API integrations using this token ID before expiration to prevent disruptions. If needed, you can extend the expiration date later.
4. Email
  Provide the email address of the person managing this service user's credentials. DigiCert ONE does not send emails to this address, so communicate any necessary details directly.
5. Accounts that can use this service user
  Select the accounts that can use this service user for their API integrations.
6. DigiCert ONE Manager access
  Assign one or more DigiCert ONE Managers. The service user can access the API for each assigned manager
Assign accounts and access:
1. In the Accounts that can use this service user field, select the accounts this service user needs to interact with.
2. In the DigiCert ONE Manager access field, assign one or more managers the service user will access via the API.
Select Next.
On the Roles and permissions page, select the user roles for each manager assigned to the service user.
Tip
Only assign roles necessary for the task or integration. If required, you can update these roles later.
Select Create service user.
In the Service user token ID window, copy the ID and save it securely.
Important
The token ID is displayed only once and cannot be recovered if lost.
After saving the token ID, select Close.

API key authentication

Use an API key for straightforward, stateless authentication.

Make API requests:

curl -X GET \
-H "x-api-key: <SERVICE_USER_KEY>" \
https://one.digicert.com/account/api/v1/user

Rotate and scope keys:

Treat keys like passwords. Store securely and rotate as needed.
Assign only roles necessary for each service user (least privilege).

Important

If a key expires or is disabled, every integration using it immediately stops. Monitor expiry dates and proactively rotate keys.

Certificate authentication (mTLS)

mTLS replaces API keys with a secure X.509 digital client certificate for verifying your identity as a service user during API requests.

Important

Certificates can only be downloaded once. Securely store both the certificate file and its password immediately after generation.

Create a client authentication certificate (UI)

Sign in to DigiCert ONE.
In the Manager menu (grid at top right), select Account.
In the Account menu, select Access > Service users.
In the Friendly name column, select the service user's friendly name.
Navigate to the Client authentication certificates section.
Select Create client authentication certificate.
Provide the following information:
1. Nickname
  This is the friendly name shown on the Service user details page. The name must be unique and may only include letters, numbers, spaces, dashes, and underscores.
2. End date
  Enter an expiry date for the certificate.
  Tip
  Make note of the expiration date. You must generate a new certificate and update all API integrations using the certificate before it expires. If you don't, the API token integrations will stop working.
3. Encryption
  Select an encryption algorithm to use for securing communications. DigiCert recommends AES (Advanced Encryption Standard), which is the default selection.
4. Signature hash algorithm
  Select a hash function to use for verifying data integrity.
Select Generate certificate.
Copy the certificate's password and store it in a secure location.
Important
This password is required for installation and API requests. You will not be able to retrieve it later.
Select Download certificate and save the certificate.
Note
You cannot download the certificate again. If lost, you must generate a new certificate.
Select Close.

API requests with mTLS

With curl, your request looks like:

curl --cert /path/auth-cert.pem --key /path/to/auth-key.pem \
  https://clientauth.one.digicert.com/account/api/v1/user

Use the clientauth. hostname and omit the x-api-key header.

Warning

If the linked service user is disabled or expired, the certificate stops working—even if the certificate itself is valid. Ensure service users remain active and manage certificates proactively.

API troubleshooting basics

Table 2. Symptom, cause, and quick fix

Symptom	Likely cause	Quick fix
401 Unauthorized	Missing/invalid `x-api-key` or expired certificate	Verify the `x-api-key` header; confirm the service user is active.
403 Forbidden	Authenticated but lacks required role	Add the needed role in Account Manager or use a different key.
429 Too Many Requests	Burst traffic	Implement backoff; spread calls across service users.
503 Service Unavailable	Maintenance window	Retry after header; escalate if >10 min.
SSL handshake failure when using mTLS	Wrong certificate, key mismatch, or incorrect URL	Check cert/key pair and ensure URL prefix is correct.
Everything stopped at midnight	Key or service user reached end date	Create/rotate the key before expiry; update all integrations.
Works in demo, fails in prod	Using demo key against prod hostname	Generate a new key in production; update `DC_BASE` environment variable.

What's next?

Make your first API call Walk through prerequisites, environment setup, and pagination.
Error handling & rate limits Decode 401/403 responses and implement retry strategies.

In this section: