SSL Certificates

Available on: Plus Pro Elite

1. What This Feature Does

SSL Certificates provides automated issuance of Let's Encrypt TLS certificates for domains on user-imported zones. When you request a certificate, CertaDNS performs a DNS-01 ACME challenge by automatically creating the required _acme-challenge TXT record in your zone's DNS. Once validated, the certificate and private key are available for download as PEM files. Each certificate supports a primary domain and optional Subject Alternative Names (SANs).

Elite plan subscribers can issue wildcard certificates (e.g., *.example.com). Pro and Elite subscribers can enable automatic renewal, which triggers 30 days before expiration. Certificates are tracked through a lifecycle of states: pending, validating, issued, failed, expired, and revoked.

2. When You Should Use It

• You host web services or APIs on domains managed through CertaDNS and need HTTPS/TLS certificates.
• You want automated certificate issuance without manually completing ACME challenges or managing DNS records.
• You need free, trusted certificates from Let's Encrypt for production or staging environments.
• You manage multiple subdomains and want to issue individual certificates or wildcards (Elite plan) without external tooling.
• You need automatic renewal (Pro/Elite plans) to prevent expiration without manual intervention.

3. When You Should Not Use It

• Extended Validation (EV) certificates: Let's Encrypt only issues Domain Validated (DV) certificates. For EV or Organization Validated (OV) certificates, use a commercial Certificate Authority.
• Non-DNS domains: Certificates can only be issued for domains on zones you have imported and verified. Public CertaDNS zones (e.g., certadns.com) do not support certificate issuance.
• Offline or internal domains: Let's Encrypt requires public DNS resolution and external validation. For internal-only domains, use a private CA.
• Custom certificate options: The system uses RSA 2048-bit keys and Let's Encrypt defaults. For custom key types (e.g., ECDSA) or non-Let's Encrypt CAs, generate certificates externally.

4. Prerequisites

• A paid CertaDNS subscription (Plus, Pro, or Elite). Free plan users cannot issue certificates.
• A verified DNS zone imported under your account. See Managed DNS Zones for instructions on importing and verifying a zone.
• The domain for which you are requesting the certificate must be under one of your imported zones (e.g., to issue for app.example.com, you must own the example.com zone).
• For wildcard certificates: Elite plan subscription.
• For auto-renewal: Pro or Elite plan subscription.

5. How It Works (Brief)

When you create a certificate, CertaDNS generates a 2048-bit RSA private key and a Certificate Signing Request (CSR). It then initiates an ACME order with Let's Encrypt. For each domain or SAN, CertaDNS retrieves a DNS-01 challenge token, calculates the required TXT record value (SHA256 hash of the JWK thumbprint, base64url-encoded), and sets _acme-challenge.domain in PowerDNS. After a 5-second propagation delay, the ACME server is notified and CertaDNS polls the authorization status (up to 30 iterations at 2-second intervals). Once all authorizations succeed, the CSR is finalized and the certificate is downloaded. The TXT records are cleaned up after validation completes.

Certificates transition through states: pending (initial), validating (ACME challenge in progress), issued (successfully obtained), failed (issuance or renewal failed), expired (past expiration date), or revoked (revoked with Let's Encrypt). Pro and Elite users with auto-renewal enabled will have the system automatically renew certificates 30 days before expiration. The renewal process repeats the ACME challenge and updates the certificate in place.

6. How to Use It

Requesting a certificate

1. Navigate to Dashboard > SSL Certificates.
2. Review the limits card at the top to verify your current certificate count and maximum allowed.
3. Click Request Certificate in the top right. (This button is disabled if you have reached your plan's certificate limit.)
4. In the Create Certificate modal:
   • Select a zone from the dropdown. Only your imported zones are listed.
   • Enter the domain (e.g., app.example.com). The domain must be under the selected zone.
   • Optionally enter additional SANs as a comma-separated list (e.g., www.example.com, api.example.com). All SANs must also be under the selected zone.
   • If you are on the Elite plan, you can check the Wildcard checkbox to issue a wildcard certificate (*.example.com). This option is disabled on Plus and Pro.
   • If you are on the Pro or Elite plan, you can check the Auto-Renew checkbox to enable automatic renewal 30 days before expiration. This option is disabled on Plus.
5. Click Request Certificate.
6. The certificate appears in the list with a pending status. Issuance is asynchronous and typically completes within 60 seconds.
7. Once the status changes to issued, the certificate is ready for download.

Downloading a certificate

1. In the certificate list, locate the certificate with issued status.
2. Click the download icon in the Actions column.
3. The Download Certificate modal displays the certificate PEM and private key PEM in separate text areas.
4. Use the Copy button to copy each PEM block to your clipboard, or click Download Certificate and Download Private Key to save as .crt and .key files.
5. The modal includes a security warning about protecting the private key. Store the private key securely and do not expose it publicly.

Renewing a certificate manually

1. In the certificate list, click the renew icon in the Actions column for the certificate.
2. Confirm the renewal in the dialog.
3. The certificate status changes to validating while the ACME challenge repeats.
4. Once complete, the status returns to issued and the certificate is updated with a new expiration date.

Enabling or disabling auto-renewal

1. Pro and Elite users can toggle auto-renewal for any certificate.
2. In the certificate list, click the auto-renew toggle icon in the Actions column.
3. The setting is saved immediately. Certificates with auto-renewal enabled will be renewed automatically 30 days before expiration.

Deleting a certificate

1. In the certificate list, click the trash icon in the Actions column.
2. Optionally select the Revoke with Let's Encrypt checkbox if you want the certificate revoked at the CA level (recommended for compromised keys).
3. Confirm the deletion.
4. The certificate is deleted from CertaDNS. If revocation was selected, it is also revoked with Let's Encrypt and marked as revoked before deletion.

7. Inputs and Settings

Field	Description	Constraints
Zone	The parent DNS zone under which the domain exists.	Must be an imported, verified zone owned by your account.
Domain	The primary domain for the certificate (e.g., app.example.com).	Must be under the selected zone. Cannot already have an active certificate.
Additional SANs	Comma-separated list of additional domains to include in the certificate (e.g., www.example.com, api.example.com).	All SANs must be under the selected zone. Optional.
Wildcard	If checked, issues a wildcard certificate (*.example.com) that matches any subdomain.	Elite plan only. Disabled on Plus and Pro.
Auto-Renew	If checked, the certificate will be automatically renewed 30 days before expiration.	Pro and Elite plans only. Disabled on Plus.

Certificate key and algorithm

All certificates use RSA 2048-bit private keys. ECDSA or custom key sizes are not supported. The CSR and private key are generated server-side and never leave the CertaDNS infrastructure unencrypted.

8. Outputs and Results

Certificate list columns

Column	Description
Domain	Primary domain name in monospace font. Wildcard certificates display *.example.com.
SANs	Count of additional Subject Alternative Names, or "—" if none.
Status	Badge with certificate state: issued (green CheckCircle icon), pending or validating (yellow animated Clock icon), failed (red XCircle icon), expired (orange AlertCircle icon), revoked (gray).
Issued	Timestamp of successful issuance, or "—" for non-issued certificates.
Expires	Expiration date with countdown. Green (>30 days), yellow (7-30 days), red (<7 days). "—" for non-issued certificates.
Auto-Renew	Green checkmark if enabled, gray "—" if disabled or unavailable.
Actions	Download (for issued certificates), Renew, Toggle Auto-Renew (Pro/Elite), Delete.

Limits card

Display	Description
Current / Max	Number of certificates issued out of plan maximum (e.g., "3 / 25").
Wildcard Available	Green checkmark (Elite) or red X (Plus/Pro).
Auto-Renewal Available	Green checkmark (Pro/Elite) or red X (Plus).

API response

The certificate list endpoint returns:

{
  "certificates": [ ... ],
  "limits": {
    "max_certificates": 25,
    "current_count": 3,
    "wildcard_enabled": false,
    "auto_renew_enabled": true
  }
}

Each certificate object includes:

{
  "id": "cert_abc123",
  "domain": "app.example.com",
  "sans": ["www.example.com"],
  "is_wildcard": false,
  "auto_renew": true,
  "status": "issued",
  "issued_at": "2026-01-15T10:30:00Z",
  "expires_at": "2026-04-15T10:30:00Z",
  "next_renewal_at": "2026-03-16T10:30:00Z"
}

9. How to Interpret Results

Normal

• Certificate shows issued status with a green CheckCircle icon. The issued and expiration dates are displayed, and the download button is enabled.
• After requesting a certificate, the status changes from pending to validating to issued within 60 seconds. This progression is expected.
• Certificates with auto-renew enabled and more than 30 days until expiration show a next_renewal_at timestamp in the future.

Unexpected or worth investigating

• failed status: The ACME challenge or certificate finalization failed. Check the certificate logs endpoint for error details. Common causes: DNS propagation delay, zone misconfiguration, or Let's Encrypt rate limits.
• validating status for more than 2 minutes: The ACME challenge is taking longer than expected. This may indicate DNS propagation issues or ACME server delays. Wait or check the logs.
• Expiration countdown in red (<7 days): The certificate is about to expire. Renew immediately if auto-renewal is not enabled or has failed.
• Auto-renewal failed: The certificate status may remain issued but the next_renewal_at field is in the past. Check logs and attempt manual renewal.

Common interpretation mistakes

• Expecting instant issuance: Certificate issuance is asynchronous. The pending and validating states are normal and can last up to 60 seconds. Do not attempt to download until the status is issued.
• Confusing certificate PEM and private key: The certificate PEM is public and safe to distribute. The private key PEM must remain confidential and should never be committed to version control or shared publicly.
• Assuming auto-renewal is retroactive: Auto-renewal only applies to certificates created or updated with the setting enabled. Existing certificates without auto-renewal will not be renewed automatically until the setting is toggled on.

10. Common Issues and Explanations

"Certificate limit reached for plan" error

You have issued the maximum number of certificates allowed by your plan. Delete unused certificates or upgrade to a higher plan. Limits: Plus=5, Pro=25, Elite=100.

"Certificate management requires paid subscription" error (403)

Free plan users cannot issue SSL certificates. Upgrade to Plus, Pro, or Elite to access this feature.

"Wildcard certificates require Elite plan" error (403)

Wildcard certificate issuance is restricted to Elite subscribers. The wildcard checkbox is disabled on Plus and Pro plans. Upgrade to Elite or request a non-wildcard certificate.

"Auto-renewal requires Pro or Elite plan" error (403)

Auto-renewal is only available on Pro and Elite plans. Plus users must manually renew certificates before expiration. Upgrade to Pro or Elite to enable auto-renewal.

"Certificate already exists for domain" error (409)

A certificate for the specified domain already exists. Each domain can only have one active certificate. Delete the existing certificate if you need to re-issue.

"Domain not under zone" error (400)

The domain you entered is not a subdomain of the selected zone. For example, if you selected example.com as the zone, you can issue for app.example.com but not app.other.com. Verify the zone selection.

"Zone not found or no permission" error (404)

The selected zone does not exist or is not owned by your account. Verify that the zone is listed under your imported zones. If the zone was recently added, ensure it has been verified.

Certificate stuck in validating state

The DNS-01 challenge may be waiting for DNS propagation or the ACME server is delayed. Wait up to 2 minutes. If the status does not change, check the certificate logs for specific ACME errors. DNS propagation issues are common if the zone was recently modified.

Certificate shows failed after creation

The ACME challenge failed. Use the GET /certificates/{id}/logs endpoint to retrieve detailed error messages. Common causes: invalid DNS configuration, Let's Encrypt rate limits, or network issues during challenge validation. Verify that the zone's nameservers are correctly set and responding.

Downloaded certificate does not match expected domain

Verify that you downloaded the correct certificate from the list. Each certificate's primary domain is displayed in the Domain column. If you requested SANs, they are included in the certificate PEM under the Subject Alternative Name extension.

Private key missing or incorrect

If the private key is not displayed in the download modal, the certificate data may be incomplete. This indicates a backend issue. Check the certificate status. If the status is issued but the download fails, contact support or attempt manual renewal to regenerate the key.

11. Limits and Constraints

Constraint	Free	Plus	Pro	Elite
Maximum certificates	0	5	25	100
Wildcard support	No	No	No	Yes
Auto-renewal	No	No	Yes	Yes
Manual renewal	No	Yes	Yes	Yes
API access	No	Yes	Yes	Yes

• Certificates can only be issued for domains under imported, verified zones. Public CertaDNS zones (e.g., certadns.com) do not support certificate issuance.
• Each domain can have only one active certificate. Attempting to issue a duplicate certificate for the same domain returns a 409 error.
• Let's Encrypt enforces external rate limits: 50 certificates per registered domain per week, 5 duplicate certificates per week. These limits apply globally across all Let's Encrypt clients, not just CertaDNS.
• Certificate issuance is asynchronous. The POST /certificates/ endpoint returns immediately with a pending status. Poll the certificate object or rely on status updates to determine when issuance completes.
• Private keys are generated server-side using RSA 2048-bit. ECDSA, RSA 4096, or custom key types are not supported.
• Auto-renewal triggers 30 days before expiration. Certificates renewed manually reset the next_renewal_at timestamp.

12. Related Features

• Managed DNS Zones — Import and verify DNS zones required for certificate issuance.
• Dynamic DNS Domains — Create subdomains that can be pointed to with certificates.
• DNS Record Management — Manage DNS records within imported zones, including A, AAAA, CNAME, and TXT records used during ACME challenges.

13. Updates and Behavior Changes

• Certificate limits on the Plus plan were increased from 3 to 5 certificates.
• Wildcard certificate support was added for Elite plan subscribers.
• Auto-renewal was introduced for Pro and Elite plans, triggering 30 days before expiration.
• The DNS-01 challenge propagation delay was reduced from 10 seconds to 5 seconds to improve issuance speed.