Troubleshoot the private trust stack

Use this page to diagnose failed runs and requests with uncertain results across DigiCert® Account Manager, DigiCert® Private CA, DigiCert® Device Trust Manager, and DigiCert® Software Trust Manager. Use the private trust stack 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.

Start with the credential’s effective access. GET /account/api/v1/role returns role names without their permissions, so it cannot identify why a request was refused. Retrieve the service user instead:

curl --fail-with-body --silent --show-error \
  "https://<host>/account/api/v1/user/${SERVICE_USER_ID}" \
  -H "x-api-key: ${BOOTSTRAP_API_TOKEN}" |
  jq '[.applications[] | {name, roles, permissions}]'

Compare the assigned roles and returned permission codes against the required capabilities. The product-to-role-key map identifies which key in GET /account/api/v1/role holds candidate roles for the product that refused the request. Keep role names and effective permission codes separate when comparing them.

If a required permission is missing, retrieve the roles for that product, select a role whose display_name and description match the capability, and update the user with PUT /account/api/v1/user/{user_id} if your access policy permits. Prefer replacing the service user over adding a broad administrator role.

If the documented role and permission checks pass, confirm that the CA, template, profile, policy, and division belong to or are shared with the same account_id. If resource scope is also correct, capture the request ID and response body: the operation might require an additional deployment-specific permission or product control.

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. Apply the complete checks in Select the device certificate template or Select the code-signing certificate template, including account availability.

Both selection steps report the same error for every failed condition. Identify the failing condition before changing anything. The name parameter on both endpoints matches templates whose name contains the value. A near-miss name therefore returns the record and then fails the exact-name check.

• For Device Trust Manager, drop the name parameter and evaluate the conditions one at a time with the listing in If no template is eligible.
• For Software Trust Manager, drop the filters when you need to inspect all available categories, then inspect status, type, template, body.issue_types, and body.extensions.extended_key_usage.required_usages on each returned record. Only the name filter is documented as a contained-string match.

Do not relax the selection criteria. Hosted Software Trust Manager template changes go through DigiCert Support. For Device Trust Manager, an authorized administrator might be able to clone or edit a template; other operations can require system-scoped access. If your deployment has no authorized administrator, contact DigiCert Support or your account representative.

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 device registration, set server_side_key_gen: true and provide the registration endpoint’s uppercase key_type, key_format, and key_syntax values. The policy must allow server-side generation.

If the profile requires user-supplied fields, include them in certificate_policies.bootstrap[].attributes as name and value pairs.

Device registration fails or has an uncertain result

Do not automatically repeat POST /devicetrustmanager/api/v4/device/registration. Search the device inventory by the exact unique name and intended group first. If the device exists, registration succeeded even if the client did not retain a successful response.

Confirm that:

• The request uses /devicetrustmanager/api/v4/device/registration, not the certificate-issuance requestCertificate endpoint.
• The request sends the original passcode in x-passcode and omits x-api-key.
• The top level contains name, account_id, device_group_id, and certificate_policies.
• The bootstrap entry contains the matching certificate policy, server_side_key_gen: true, and uppercase RSA_2048, PEM, and PKCS8 values.
• Required certificate fields use attributes[].name and attributes[].value.
• The group assignment contains the matching certificate and authentication policy IDs and reports status: ACTIVE.

If the device exists, query certificate inventory using the account, division, certificate policy, and exact common name. Then require the result’s device.id to match the registered device. Do not use the certificate endpoint’s device_group_id filter for this recovery because it can exclude an otherwise retrievable registered certificate.

If the registration response containing the server-generated private key was lost, inventory recovery cannot prove that the key matched the certificate. Stop the full validation path rather than registering a duplicate. Follow the approved product recovery or cleanup process, or begin a new isolated run with a new name. If no device exists, preserve the request timestamp, endpoint, HTTP status, and response headers before deciding whether a new uniquely named request is safe.

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.

Software Trust reports that the account license is not found

Stop the signing workflow and confirm that the target account has an active Software Trust Manager license that permits test-keypair generation, certificate generation, and hash signing. Template visibility and effective permissions such as GENERATE_SM_KEYPAIR and SIGN_SM_HASH do not prove that the product license is enabled for the account.

Treat a license error from keypair creation as an uncertain create result. Follow Recover an uncertain keypair create result and search by the exact unique alias before retrying or creating a replacement. If signing returns the license error, preserve the response and correlation information and stop; no signature is available to verify.

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.

Product documentation limits TEST keypairs to a maximum of 30 days. The general API schema includes NO_EXPIRY in the enum, but do not request non-expiring behavior for this test workflow. Omit the optional expiry_type as shown in Create a test keypair with both authentication factors, then confirm the returned expiry is finite and no more than 30 days. Alternatively, use a finite expiration that your product and signing policy explicitly approve.

For any non-2xx response, timeout, or lost response, do not assume the keypair was rolled back and do not automatically repeat the POST. Search by the exact retained alias first.

Private trust certificate profile rejects the issuing CA field

Use ca_certificate_profile_request.ca.id for the issuing CA. The request does not accept an ica_id property at any level. Also check signing_ica_id, the organization ID, the Software Trust Manager code-signing template, and the CA_PROFILE type. The required properties are name and profile_type at the top level and certificate_template_id and body inside ca_certificate_profile_request. Send body as an empty array when the profile adds no attribute overrides. If the request is still rejected, capture the request ID and response body and contact DigiCert Support.

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 signature string is decoded from Software Trust’s documented default Base64 representation, 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.