--- title: "Troubleshoot the private trust stack" description: "Diagnose cross-product authorization, configuration, enrollment, path-validation, and signing failures." source_url: https://dev.digicert.com/solutions/private-trust-stack/troubleshoot.html --- # Troubleshoot the private trust stack Diagnose cross-product authorization, configuration, enrollment, path-validation, and signing failures. 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](https://dev.digicert.com/md/solutions/private-trust-stack/reference.md) to look up identifiers, authentication methods, and request formats. For general authentication, authorization, throttling, and server errors, see [API error handling and rate limits](https://dev.digicert.com/md/get-started/error-handling-rate-limits.md). 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 | Signal | Start here | |--------|------------| | `403` or client-certificate authentication | [Account and identity failures](#account-and-identity-failures) | | Certificate template eligibility | [Cross-product resource failures](#cross-product-resource-failures) | | CA assignment or hierarchy | [Private CA failures](#private-ca-failures) | | Division, profile, policy, or group | [Device Trust configuration failures](#device-trust-manager-configuration-failures) | | Passcode, approval, enrollment, or path validation | [Device enrollment failures](#device-enrollment-failures) | | Profile, keypair, signing authentication, trust, or signature | [Software Trust failures](#software-trust-manager-failures) | ## 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: ```bash 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: ```text https:///certificate-authority/api/v1 ``` `https:///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=&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](https://dev.digicert.com/md/solutions/private-trust-stack/phase-3-device-infrastructure.md#step-33-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](https://dev.digicert.com/md/solutions/private-trust-stack/phase-3-device-infrastructure.md#step-34-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: ```json { "policy_id": "IOT_", "assignment_name": "Private device bootstrap certificate", "type": "bootstrapCertificate", "auth_policy_id": "", "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](https://dev.digicert.com/md/solutions/private-trust-stack/phase-3-device-infrastructure.md#step-33-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: ```bash 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](https://dev.digicert.com/md/solutions/private-trust-stack/phase-2-private-trust-anchor.md#step-23-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./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](https://dev.digicert.com/md/solutions/private-trust-stack/operate.md). - [Look up implementation status, identifiers, and request formats](https://dev.digicert.com/md/solutions/private-trust-stack/reference.md). - [Return to the solution overview](https://dev.digicert.com/md/solutions/private-trust-stack.md).