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.

Pagination:
All list endpoints use cursor-based pagination. Pass limit (default 100, max 1000) and an optional cursor from a previous response. Responses include a pagination object with next_cursor (opaque string, or null on the last page) and has_more (boolean). Clients advance sequentially using next_cursor; random page access and total result counts are not supported.

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.
    • List / Get / Update Accounts: Query, retrieve, and modify existing accounts.
    • Delete an Account: Remove an account if it is no longer needed. Deletion is permanent and affects the ability to manage existing orders.
    • EAB Credential Management: Create, list, and delete External Account Binding (EAB) credentials for use with ACME.
    • Account Groups: Organize accounts into groups and assign issuance policies to them.
    • Issuance Policies: Create and manage certificate issuance policies that limit order creation rates and active certificate volume.
  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 account lookup — a persistent unique ID assigned at creation — and is associated with a reseller by the API key. An email address is required at creation but can be changed later and is not the primary identifier.

To create an account, send a POST request to the /v1/account endpoint. The request must include at least an email address for the account. The generate_eab JSON parameter should be set True to generate a new set of EAB credentials (KID and HMAC) for use with ACME. If this account will only be used with the Reseller API, then generate_eab may be omitted or false.

Accounts may be thought of as a "Root Account" for use with the Reseller API, which may contain multiple "EAB Accounts" under it for use with ACME. At present, an account may have an unlimited number of EAB accounts associated with it.

Important Details:

  • Account Lookup: On account creation, the account is assigned an account lookup which is the persistent unique identifier for all subsequent operations (deletion, update, ordering, etc.). Always retain this value.
  • Efficient Account Creation: If no root account exists for the provided email when generating EAB credentials (generate_eab=true) the root account will be generated automatically. Note that creating an account does not reactivate a previously deleted account, but rather creates a new account with the same email address.
  • 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. Since email can be changed via the update endpoint, the account lookup is the only stable identifier.
  • 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 lookup value 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 but will create a new account with the same email address.

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

Account Query​

You can list all accounts associated with your reseller by sending a GET request to the /v1/account endpoint. Results can be filtered using query parameters such as customer_email, is_suspended, limit, and cursor.

To retrieve a specific account, send a GET request to /v1/account/{lookup}, where {lookup} is the account lookup code assigned at creation.

Account Update​

To update an existing account, send a PATCH request to /v1/account/{lookup}. You can update the following fields:

  • customer_email — Change the email address associated with the account.
  • suspended — Suspend or unsuspend the account.

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 /v1/account/{lookup}, where {lookup} is the account lookup code assigned at creation.

Expected Behavior:

  • The account associated with the specified lookup 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.

EAB Credential Management​

External Account Binding (EAB) credentials are used to authenticate ACME clients with the IdenTrust Certificate Management System. EAB credentials consist of a Key Identifier (KID) and an HMAC key.

While EAB credentials can be generated during account creation (by setting generate_eab=true), you can also manage them independently:

  • Create: Send a POST request to /v1/account/{lookup}/eab-credential to generate a new EAB credential for an account.
  • List for Account: Send a GET request to /v1/account/{lookup}/eab-credential to list all EAB credentials for a specific account.
  • List All: Send a GET request to /v1/eab-credential to list all EAB credentials across all accounts.
  • Get: Send a GET request to /v1/eab-credential/{kid} to retrieve a specific EAB credential.
  • Delete: Send a DELETE request to /v1/eab-credential/{kid} to delete an EAB credential.

Account Groups​

Account groups allow you to organize accounts and apply issuance policies to multiple accounts at once.

  • Create: Send a POST request to /v1/account-group.
  • List: Send a GET request to /v1/account-group.
  • Get: Send a GET request to /v1/account-group/{group_lookup}.
  • Update: Send a PUT request to /v1/account-group/{group_lookup}.
  • Delete: Send a DELETE request to /v1/account-group/{group_lookup}.

Managing Group Members​

  • List Members: Send a GET request to /v1/account-group/{group_lookup}/member.
  • Add Members: Send a POST request to /v1/account-group/{group_lookup}/member.
  • Remove Members: Send a DELETE request to /v1/account-group/{group_lookup}/member.

Managing Group Policies​

  • List Policies: Send a GET request to /v1/account-group/{group_lookup}/policy.
  • Assign Policy: Send a POST request to /v1/account-group/{group_lookup}/policy/{policy_lookup}.
  • Remove Policy: Send a DELETE request to /v1/account-group/{group_lookup}/policy/{policy_lookup}.

Issuance Policies​

Issuance policies limit order creation and active certificate volume to prevent abuse and support tiered service behavior. Policies can be assigned to account groups to enforce rules across multiple accounts.

A policy contains one or more limits, each targeting a measurable property with an enforcement interval and optional filters.

Supported Properties:

  • ordersCreated — Total orders created for the account scope within the selected interval.
  • validCertificates — Total currently valid certificates for the account scope, optionally filtered by certificate profile.

Supported Filters:

  • api — Array of API codes to scope the limit to (e.g., ["ACME"], ["RESELLER"], or both).
  • certificateProfile — Case-insensitive profile code match (e.g., TLS-90d).
  • clientTags — Array of client tags. Matching uses case-insensitive overlap semantics.

If a filter is omitted, it behaves as a wildcard.

Supported Intervals for ordersCreated: 1s, 1m, 1h, 1d, calendarMonth, calendarYear.

Example Policy:

{
    "version": 1,
    "name": "ACME Burst Guard",
    "description": "Limits ACME order spikes during traffic bursts",
    "limits": [
        {
            "property": "ordersCreated",
            "interval": "1h",
            "limit": 4,
            "filters": {
                "api": ["ACME"],
                "certificateProfile": "TLS-90d"
            }
        }
    ]
}

API Operations:

  • Create: Send a POST request to /v1/policy.
  • List: Send a GET request to /v1/policy.
  • Get: Send a GET request to /v1/policy/{lookup}.
  • Update: Send a PUT request to /v1/policy/{lookup}.
  • Delete: Send a DELETE request to /v1/policy/{lookup}.

2. Ordering a Certificate​

Order Creation​

To request a new TLS certificate, submit a POST request to the /v1/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 /v1/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 /v1/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 /v1/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 /v1/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 /v1/challenge/{challenge_lookup}.

Challenge Workflow​

  1. Generate Challenges:
    For each domain, generate authorization challenges by sending a POST request to /v1/authz/{auth_lookup}/challenges. The {auth_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 /v1/challenge/{challenge_lookup}.

  3. Monitor Challenge Status:
    Check the status of each authorization and its challenges by sending a GET request to /v1/authz/{auth_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 /v1/authz/{auth_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 /v1/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 /v1/authz/{auth_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 /v1/order/{order_lookup}/finalize endpoint, where {order_lookup} is the unique identifier for the certificate order.

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 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 /v1/certificates endpoint. You can filter the results using query parameters such as customer_email, account_lookup, eab_kid, certificate_status, limit, and cursor.

Get Certificate Metadata​

To retrieve detailed metadata for a specific certificate, send a GET request to /v1/certificates/{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. Send a GET request to /v1/certificates/{order_lookup}/linting using the order lookup value for the certificate.

Get Base64-encoded DER Certificate​

To obtain the certificate in a machine-readable format, send a GET request to /v1/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 /v1/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 POST request to the /v1/certificates/{order_lookup}/revocation endpoint. The {order_lookup} is the unique identifier for the certificate order. The request body should include:

  • revocation_reason — One of the allowed reason codes listed above (e.g., UNSPECIFIED, KEY_COMPROMISE).
  • revocation_date — (Optional) An ISO 8601 date-time indicating when the certificate should be considered revoked (e.g., 2018-06-15T14:07:09Z). Defaults to the current date/time if omitted.

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.
  • 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 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​