Skip to main content

IdenTrust Certificate Management System

Integration Guide​

Abstract​

The IdenTrust Certificate Management System provides a comprehensive, standards-based platform for the lifecycle management of TLS (Transport Layer Security) certificates. TLS certificates are essential for securing communications over the internet, ensuring data privacy, and authenticating the identity of websites and services. The process of obtaining and managing these certificates follows industry best practices and regulatory requirements, including those defined by the IETF and CA/Browser Forum.

This document serves as an integration guide for interacting with the IdenTrust Certificate Management System via its RESTful APIs. It describes the end-to-end workflow required for a reseller to manage PKI for their customers.

By following the procedures outlined in this guide, resellers and integrators can automate and streamline the management of TLS certificates for their customers, reducing manual effort and minimizing the risk of errors or non-compliance.

Integration Workflow Overview​

API Authentication:
All API requests described in this document require a Bearer Token retrieved via OAuth credential exchange. See Authentication for details.

The process for ordering, issuing, and managing a TLS certificate through the IdenTrust system typically involves the following steps:

  1. Account Management
    • Create an Account: Establish a new account if one does not already exist. Each account is associated with a unique email address and is required for all subsequent operations.
    • Delete an Account: Remove an account if it is no longer needed. Deletion is permanent and affects the ability to manage existing orders.
  2. Ordering a Certificate
    • Submit an Order: Place a new certificate order for one or more domains.
    • Cancel an Order: Cancel an open order if it is no longer required.
    • Query Order Status: Check the current status of any order at any time.
  3. Authorization Challenges
    • Request Challenges: Obtain domain control challenges for each domain in the order.
    • Deactivate Authorization: Cancel an authorization, which also cancels the associated order.
    • Query Challenge Status: Retrieve the current status of all authorization challenges.
  4. Challenge Completion
    • Complete Challenges: Satisfy one of the available domain control challenges (DNS, HTTP, or EMAIL) for each domain.
    • Deactivate Challenge: Optionally deactivate a challenge, which also cancels the associated order.
  5. Order Finalization
    • Finalize Order: Complete the order process, triggering certificate issuance if all challenges are passed.
  6. (Optional) Reseller Issuance Notification
    • Webhook Callback: Summary of certificate issuance is sent to reseller.
  7. Certificate Retrieval
    • Retrieve Certificates: Download issued certificates and view their metadata in various formats.
  8. Certificate Revocation
    • Revoke Certificate: Permanently revoke a certificate if it is compromised or no longer needed.
  9. (Optional) Reseller Revocation Notification
    • Webhook Callback: Summary of certificate revocation is sent to reseller.

1. Account Management​

Account Creation​

Before you can submit a certificate order, you must first create an account in the IdenTrust Certificate Management System. Each account is uniquely identified by an email address and is associated with a reseller by the API key. The account creation process is designed to be simple, secure, and idempotent.

To create an account, send a POST request to the /account endpoint. The request must include at least a unique email address for the account. Additional information, such as reseller code, may be required depending on your integration.

Important Details:

  • Idempotency: If an account already exists for the provided email and reseller API key, the existing account record will be returned. Creating an account does not reactivate a previously revoked or deleted account.
  • Account Uniqueness: Account records are unique to an email address within the domain of a reseller. The same email address may be used for different accounts by different resellers API keys.
  • Jurisdiction Restrictions: Account creation requests using email addresses from prohibited jurisdictions will be rejected. As of April 2025, these jurisdictions include: Belarus, Cuba, North Korea, Iran, Libya, Myanmar, Russia, Sudan, South Sudan, Syria, Venezuela, and Yemen.

What to Expect:

  • After account creation, retain the account identification values (such as the account ID and KID) for use in all subsequent API requests related to this account.
  • If you attempt to create an account with an email address from a prohibited jurisdiction, the request will be denied with an appropriate error message.
  • If you attempt to create an account that has previously been deleted or revoked, the system will not reactivate it; a new unique email address must be used.

Note:
Account creation is a prerequisite for all certificate management operations.

Account Deletion​

If an account is no longer needed, it can be permanently deleted from the system. Deleting an account ensures that no further certificate orders can be placed or managed under that account, and the account cannot be reactivated. However, any existing certificate orders or previously issued certificates associated with the account will remain in their current state (active or revoked), but cannot be modified or renewed.

To delete an account, send a DELETE request to the /account endpoint, specifying the email address of the account to be deleted as a query parameter. The email address must be URL-encoded.

Expected Behavior:

  • The account associated with submitted email address will be permanently marked as deleted.
  • All existing certificate orders for this account will remain, but no further changes (such as order cancellation or certificate renewal) can be made.
  • Any certificates already issued to this account will remain valid or revoked as before, but cannot be managed further.
  • Attempting to create a new account with the same email will not reactivate the deleted account.

Note:
Account deletion is irreversible. Ensure that all necessary certificate management actions are completed before deleting an account.

2. Ordering a Certificate​

Order Creation​

To request a new TLS certificate, submit a POST request to the /order endpoint. This request must include all information necessary for the system to process and validate the order.

Important Details:

  • The domains listed in the domains array must match those encoded in the CSR.
  • The account specified by customer_email must exist and be active.
  • If the order is accepted, you will receive authorization challenges for each domain, which must be completed before the certificate can be issued.

Order Status Query​

You can check the status of any certificate order at any time by sending a GET request to /order/{order_lookup}. This will return the current state of the order, including the status of all associated domain authorizations and challenges.

CSR Validation​

Before submitting an order, you may wish to validate your CSR to ensure it meets all requirements. To do this, send a POST request to the /validate-csr endpoint with the relevant details.

Order Cancellation​

If you need to cancel an open order before it is finalized or issued, send a DELETE request to /order/{order_lookup}.

Expected Behavior:

  • The order will be cancelled and no certificate will be issued.
  • If a certificate has already been issued, cancelling the order does not revoke the certificate. Use the certificate revocation process to revoke an issued certificate if needed.

Note:
Order cancellation is only possible before the certificate has been issued. After issuance, use the revocation endpoint to invalidate the certificate.

3. Authorization and Challenges​

After submitting a certificate order, you must prove control over each domain listed in the order. This is accomplished through authorization challenges. The IdenTrust Certificate Management System supports several industry-standard challenge types. You must successfully complete at least one challenge for each domain before the certificate can be issued.

Challenge Types Overview​

For each domain, you may choose from the following challenge types to demonstrate domain control:

DNS Challenge​

Description:
Prove control by creating a DNS TXT record at your domain’s authoritative DNS server.

Requirements:

  • Add a TXT record to your domain’s DNS zone with the name yourdomain.com and the value provided as the token in the challenge details.

Steps to Fulfill:

  1. Log in to your DNS provider’s management console.
  2. Create a new TXT record with the specified name and value.
  3. Wait for DNS propagation (may take several minutes).
  4. Notify the system that the challenge is ready by sending a POST request to /challenge/{challenge_lookup}.

HTTP Challenge​

Description:
Prove control by hosting a specific file with a given content at a well-known URL on your web server.

Requirements:

  • Place a file at http://yourdomain.com/.well-known/pki-validation/{token_filename}.
  • The file must contain the exact token value provided in the challenge.

Steps to Fulfill:

  1. On your web server, create the .well-known/pki-validation/ directory if it does not exist.
  2. Create a file named with the provided token_filename and place the token value as its content.
  3. Ensure the file is publicly accessible over HTTP.
  4. Notify the system that the challenge is ready by sending a POST request to /challenge/{challenge_lookup}.

Challenge Workflow​

  1. Generate Challenges:
    For each domain, generate authorization challenges by sending a POST request to /authz/{authorization_lookup}/challenges. The {authorization_lookup} is provided in the order response.

  2. Select and Complete a Challenge:

    • Choose one challenge type per domain.
    • Follow the instructions above to fulfill the requirements.
    • For DNS-01 and HTTP-01, notify the system when ready by sending a POST to /challenge/{challenge_lookup}.

  3. Monitor Challenge Status:
    Check the status of each authorization and its challenges by sending a GET request to /authz/{authorization_lookup}/.

    The response will include the status of each challenge (e.g., pending, valid, invalid) and any required actions or errors.

  4. Repeat as Needed:

    • You only need to complete one challenge per domain, but you may attempt multiple types if needed.
    • All required challenges must be validated before proceeding to order finalization.

Authorization Management​

  • Cancel Authorization:
    If you need to cancel an authorization (and its associated order), send a DELETE request to /authz/{authorization_lookup}.

    This action is irreversible and will prevent certificate issuance for the associated order.

Summary:

  • For each domain, select and complete at least one challenge type.
  • Use the provided API endpoints to generate, fulfill, and monitor challenges.
  • All domain challenges must be validated before you can finalize your certificate order.

4. Challenge Completion​

To prove domain control, you must successfully complete at least one challenge (DNS or HTTP) for each domain in your certificate order. The details for each challenge, including the challenge_lookup and token, are provided in the response when you generate challenges for a domain.

Proving Challenge Completion​

Once you have fulfilled the requirements for a challenge (for example, by adding the required DNS TXT record, hosting the specified file at the correct URL, or responding to the validation email), you must notify the system that the challenge is ready for verification.

To do this, send a POST request with an empty payload to the /challenge/{challenge_lookup} endpoint, where {challenge_lookup} is the unique identifier for the specific challenge you have completed.

Expected Behavior:

  • The system will attempt to verify that the challenge has been completed correctly (e.g., by checking the DNS record or HTTP resource).
  • You can poll the status of the authorization using a GET request to /authz/{authorization_lookup}/ to check if the challenge has been validated.
  • Once all required challenges for all domains in the order are marked as valid, you may proceed to finalize the order.

Important Details:

  • Only one challenge per domain needs to be completed and validated, but you may complete more than one if desired.
  • If the challenge verification fails, the system will provide error details in the authorization status response. You may correct the issue and re-notify the system as needed.
  • Challenge completion and verification must be performed for each domain listed in the certificate order.

Note:
Do not proceed to order finalization until all required challenges for all domains have been completed.

5. Order Finalization​

After all required domain challenges have been successfully validated, you must finalize the certificate order to trigger certificate issuance. Finalization confirms that you have completed all necessary steps for domain control and are ready to receive the certificate.

To finalize the order, send a POST request (with no payload) to the /authz/{authorization_lookup}/ endpoint. The {authorization_lookup} should correspond to one of the authorizations associated with your order. Finalizing any one of the authorizations will finalize the entire order, provided all challenges for all domains are valid.

Important Details:

  • All domain challenges for the order must be marked as valid before finalization will succeed.
  • If any challenges are still pending or invalid, the system will return an error and the order will not be finalized.
  • Finalization does not return the certificate itself; you must use the certificate retrieval endpoints to download the issued certificate once the order status is issued.

Note:
Order finalization is a critical step. Ensure all domain validations are complete and correct before proceeding. If you encounter errors during finalization, review the status of each domain authorization and resolve any outstanding issues.

6. (Optional) Reseller Issuance Notification​

If the reseller is configured to receive a callback notification, a request will be send with the following JSON payload will be sent upon certificate issuance.

{
  "caCertificate": "-----BEGIN CERTIFICATE-----\n(certificate body goes here)\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n(certificate body goes here)\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n(certificate body goes here)\n-----END CERTIFICATE-----",
  "certificate":"-----BEGIN CERTIFICATE-----\n(certificate body goes here)\n-----END CERTIFICATE-----"
  "certificateID":"3d5eb726c2de02bd32485e0cf084ea38449bb9f",
  "eventType":"Certificate",
  "orderNumber":"order_lookup_goes_here",
  "status":"ISSUED"}

Notes:

The callback can be optionally configured to send a Basic token in an Authorization header, if configured.

Example: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

If a non-200(OK) HTTP response is returned from the reseller or the callback request times out, the callback will be re-attempted up to three times:

1st reattempt after 5 minutes of the initial request;

2nd reattempt after 12 hours of the initial request;

3rd and final reattempt after 2 days of the initial request.

7. Certificate Retrieval​

After your certificate order has been finalized and the certificate has been issued, you can retrieve the certificate and its associated metadata using the following endpoints and procedures.

List Certificates​

To view all certificates associated with an account, send a GET request to the /certificates endpoint. You can filter the results using query parameters such as customerEmail, certificateStatus, limit, and page.

Get Certificate Metadata​

To retrieve detailed metadata for a specific certificate, send a GET request to /certificate/{order_lookup} using the unique order lookup value for the certificate.

Certificate Linting​

After a certificate is issued, you can check for compliance and best practices by retrieving linting results.

Get Base64-encoded DER Certificate​

To obtain the certificate in a machine-readable format, send a GET request to /certificates/{order_lookup}/json. You can include the certificate chain if needed by setting the includeChain parameter.

Download Certificate​

To download the certificate in a specific file format (DER, PEM, or PKCS7), optionally including the trust chain, send a GET request to /certificates/{order_lookup}/download with the appropriate query parameters.

Important Details:

  • Ensure you use the correct order_lookup value for all retrieval operations.
  • The certificate must be in the issued state before it can be retrieved.
  • If you require the full certificate chain for installation, set includeChain=true in your request.

Note:
Always verify the integrity and correctness of the retrieved certificate before deploying it to production.

8. Certificate Revocation​

Certificates may need to be revoked if they are compromised, misused, or no longer needed. Revocation is a permanent action and cannot be undone. If a certificate is revoked in error, you must submit a new order to obtain a replacement certificate.

Revocation Reasons​

When revoking a certificate, you must specify a reason. Acceptable revocation reasons are defined in RFC 5280 and include:

  • NOT_REVOKED
  • UNSPECIFIED
  • KEY_COMPROMISE (private key is suspected to be compromised)
  • CA_COMPROMISE (certificate authority is compromised)
  • AFFILIATION_CHANGED (organization or domain ownership changes)
  • SUPERSEDED (certificate replaced by a new one)
  • CESSATION_OF_OPERATION (service or domain is discontinued)
  • CERTIFICATE_HOLD (temporary hold, rarely used)
  • REMOVE_FROM_CRL (remove from certificate revocation list)
  • PRIVILEGES_WITHDRAWN (loss of privileges)
  • AA_COMPROMISE (attribute authority compromised)

Important:
If you need to change the revocation reason after revocation, only KEY_COMPROMISE is allowed as an update.

Revoking a Certificate​

To revoke a certificate, send a DELETE request to the /certificates/{order_lookup}/{revocation_reason}?revocation-date={datetime} endpoint. The {order_lookup} is the unique identifier for the certificate order, {revocation_reason} is one of the allowed reasons above, and {datetime} is the effective revocation date and time in ISO 8601 format (must be URL-encoded).

Expected Behavior:

  • The certificate associated with the specified order will be permanently revoked as of the provided date and time.
  • Revoked certificates cannot be reinstated or reactivated.
  • Any systems relying on the revoked certificate should be updated to use a new, valid certificate.

Important Details:

  • Ensure you use the correct order_lookup and specify the appropriate revocation reason.
  • The revocation date/time must be URL-encoded and in UTC (e.g., 2018-06-15T12%3A00%3A00Z).
  • Revocation is permanent. Double-check all details before submitting the request.

Note:
If a certificate is revoked in error or you need to replace it, submit a new certificate order following the standard order process.

9. (Optional) Reseller Revocation Notification​

If the reseller is configured to receive a callback notification, a request will be send with the following JSON payload will be sent upon certificate revocation.

{
  "caCertificate": "-----BEGIN CERTIFICATE-----\n(certificate body goes here)\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n(certificate body goes here)\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n(certificate body goes here)\n-----END CERTIFICATE-----",
  "certificate":"-----BEGIN CERTIFICATE-----\n(certificate body goes here)\n-----END CERTIFICATE-----"
  "certificateID":"3d5eb726c2de02bd32485e0cf084ea38449bb9f",
  "eventType":"Certificate",
  "orderNumber":"order_lookup_goes_here",
  "status":"revoked"}

Notes:

The callback can be optionally configured to send a Basic token in an Authorization header, if configured.

Example: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

If a non-200(OK) HTTP response is returned from the reseller or the callback request times out, the callback will be re-attempted up to three times:

1st reattempt after 5 minutes of the initial request;

2nd reattempt after 12 hours of the initial request;

3rd and final reattempt after 2 days of the initial request.

References​