Troubleshoot the private trust stack

Use this page to diagnose failed runs or requests with uncertain results across DigiCert® Account Manager, DigiCert® Private CA, DigiCert® Device Trust Manager, and DigiCert® Software Trust Manager. Use Reference to look up identifiers, authentication methods, and request formats.

For general authentication, authorization, throttling, and server errors, see API error handling and rate limits. Preserve the HTTP status, response body, request ID or correlation ID, endpoint, and timestamp when escalating an API failure. Never include API tokens, passcodes, client private keys, or returned device private keys in a support record.

Quick triage

Account and identity failures

A cross-product request returns 403

Authentication succeeded, but the service user lacks a required role or access to a required resource. Retrieve the assignable roles again with GET /account/api/v1/role, compare the service user’s current roles, and update it with PUT /account/api/v1/user/{user_id} if your access policy permits. Also confirm that the CA, template, profile, policy, and division belong to or are shared with the same account_id.

Client certificate does not authenticate the service user

Confirm all of the following:

• The client certificate was created for the same service user whose API token is in x-api-key.
• The request uses the clientauth. hostname for the correct tenant region.
• The certificate is enabled and within its validity period.
• The private key matches the certificate:

test "$(openssl x509 -in client.crt -pubkey -noout | openssl sha256)" = \
     "$(openssl pkey -in client.key -pubout | openssl sha256)"

Cross-product resource failures

Certificate template is rejected

List templates in the product where you create the profile. Do not use GET /certificate-authority/api/v1/template for either profile.

• The Device Trust Manager response stores templates in records. Require status: ACTIVE, type: custom, format: x509, certificate_type: end_entity, body.issue_types containing client_authentication, and a required client authentication extended key usage (EKU). For this manual, also require rsa_2048 and a common name that permits user_supplied.
• The Software Trust Manager response stores templates in items. Require status: ACTIVE, type: CUSTOM, template: TEST, body.issue_types containing code_signing, and body.extensions.extended_key_usage.required_usages containing code_signing.
• For either product, confirm that the account restrictions permit account_id.

Private CA failures

CA endpoint returns 404

Confirm that the URL includes the DigiCert Private CA base path:

https://<host>/certificate-authority/api/v1

https://<host>/ca is not the endpoint URL documented by the API reference. Template discovery does not use the DigiCert Private CA /template endpoint in this solution.

Issuing CA is not available in another product

Confirm that:

• The selected CA has status: active and is an intermediate, not the root.
• POST /certificate-authority/api/v1/ca/{device_ica_id}/accounts and POST /certificate-authority/api/v1/ca/{signing_ica_id}/accounts returned 204 for newly added assignments.
• The CA’s account_assignments contains the target account.
• device_ica_id is available to the Device Trust Manager division.
• signing_ica_id is available to the Software Trust Manager account.
• Each selected issuing CA can issue end-entity certificates and validates beneath root-ca.pem.

Device Trust Manager configuration failures

Division creation succeeds but there is no ID

The create response contains status information but not the division ID. Search with GET /devicetrustmanager/api/v4/division?account_id=<id>&name=<name>, then select the exact active name from records. Do not read id directly from the create response.

If creation returns Primary zone ID is required if a secondary zone is present, select an exact enabled rendezvous zone with is_primary_usage: true and send its ID in primary_rzone_id.

Certificate profile returns 400

Check that body is an array of objects containing key, optional, enabled, sources, and value. A value such as "body": ["BODY"] is invalid. The API requires the explicit values for allow_any_key_type, allowed_key_types, the validity duration, and all four renewal settings shown in Create the device certificate profile. Also confirm:

• certificate_template_id is the template ID from Device Trust Manager.
• divisions contains the intended division ID or the profile is intentionally account-wide.
• Each source value is supported by both the API reference and the template.
• Required fields such as the common name can be supplied during enrollment.

Certificate policy rejects the issuing CA or profile

Confirm that the request uses the full nested certificate_policy object and includes name, division_id, certificate_profile_id, ica_id, and certificate_management_methods. The profile must be available to the selected division. Inspect the successful response and require certificate_profile.id and ica.id to match the requested values.

For the SINGLE enrollment method, include the single_cert_request_parameters object from Create the REST certificate policy. The API rejects an otherwise minimal policy with Provide single request parameters. Remove fields copied from response schemas or unrelated API versions, such as digital_signing_ica_id and expired_on. The create response stores the new object in certificate_policy. Read the ID from certificate_policy.id.

Device group rejects the policies array

Each array item must be a policy-assignment object. For example:

{
  "policy_id": "IOT_<uuid>",
  "assignment_name": "Private device bootstrap certificate",
  "type": "bootstrapCertificate",
  "auth_policy_id": "<authentication-policy-uuid>",
  "status": "ACTIVE"
}

The allowed assignment types are bootstrapCertificate and operationalCertificate.

Device enrollment failures

Passcode is not found

The API reference documents a 404 response when the service cannot find the authentication passcode. Confirm that:

• The request sends x-passcode and omits x-api-key.
• The value is the original passcode, not passcode_hint.
• The passcode is active and within its usage limit and validity period.
• The request includes the device group whose policy assignment contains the matching authentication-policy override.
• The certificate policy ID matches the policy in that assignment.

Certificate signing request or private-key fields are missing

The key-generation fields are conditionally required:

• For client-side generation, submit csr and keep server_side_key_gen false or omit it.
• For server-side generation, set server_side_key_gen: true and provide private_key_format. The policy must allow server-side generation. Supply key_type when selecting a non-fixed allowed key type.

If the profile requires user-supplied fields, include them in certificate_profile_attributes.

Enrollment remains pending

If the policy requires approval, PENDING_APPROVAL is not an issued certificate. Poll the request-status endpoint using certificate_request_id. Download the approved certificate only after the status becomes APPROVED.

Enrollment returns an empty 400 response

Stop before retrying. Search for a device and certificate by the exact group, policy, and common name to determine whether the first request created anything. Then confirm that:

• The device profile contains the explicit key, validity, and renewal fields shown in Create the device certificate profile.
• The certificate policy contains single_cert_request_parameters and the successful create response was parsed from certificate_policy.
• The group assignment contains the matching certificate and authentication policy IDs and reports status: ACTIVE.
• The request uses the original passcode, includes device_group_id, sets private_key_format: pem, and omits x-api-key.

If the device and certificate lists contain no match, preserve the request timestamp, endpoint, HTTP status, and response headers and contact DigiCert Support. Do not change fields repeatedly when the response contains no diagnostic information.

Certificate-path validation fails

Inspect the end-entity issuer and both CA subjects:

openssl x509 -in device.pem -noout -subject -issuer
openssl x509 -in device-issuing-ca.pem -noout -subject -issuer
openssl x509 -in root-ca.pem -noout -subject -issuer
openssl verify -CAfile root-ca.pem -untrusted device-issuing-ca.pem device.pem

Common causes include selecting the wrong issuing CA, using a stale CA download, omitting the intermediate, or trusting the issuing CA instead of the approved root. Compare SHA-256 fingerprints with the records retained when you download and validate the CA certificates.

Software Trust Manager failures

No eligible custom test template is available

Stop before creating a certificate profile or keypair. In hosted Software Trust Manager accounts, DigiCert might control certificate-template administration. Ask DigiCert Support to create or update an active certificate template with type: CUSTOM and template: TEST. The template must require the code-signing EKU and be available to the target account. Do not substitute a SYSTEM or PRODUCTION template for this validation workflow.

Keypair creation or signing returns an authentication error

Keypair creation and signing require:

• https://clientauth.<tenant-host>/signingmanager/...
• The service user’s client certificate and matching private key.
• The same service user’s API token in x-api-key.

Supplying only the certificate or only the API token is insufficient.

Keypair request returns 400

Use a specific algorithm configuration. RSA accepts one of the documented key sizes. ECDSA and EdDSA use a supported curve. Do not send key_size: 0, and do not send both key_size and curve for one keypair.

Private trust certificate profile rejects the issuing CA field

Use ca_certificate_profile_request.ca.id for the issuing CA. Do not send a top-level ca_certificate_profile_request.ica_id property. Also check signing_ica_id, the organization ID, the Software Trust Manager code-signing template, and the CA_PROFILE type. If the request is rejected, capture the request ID and verify that the API version in your tenant matches the current API reference.

Signing certificate is not trusted for code signing

Confirm that the certificate:

• Was issued from the code-signing template rather than the device template.
• Contains the code-signing EKU.
• Chains through signing_ica_id to the root installed in the verifier’s trust store.
• Is active and within its validity period.

Private code-signing certificates are not automatically trusted by operating systems or build verifiers.

Raw-signature verification fails

Verify that the same binary digest sent in hash is used for verification, that the response signature is base64-decoded, and that the verification algorithm matches sig_alg. For the manual’s RSA example, use SHA-256 with RSA PKCS#1 v1.5 and the public key from the issued signing certificate. A successful API response alone is not signature verification.

Related pages

• Operate and maintain the solution.
• Look up implementation status, identifiers, and request formats.
• Return to the solution overview.