aziontech · GabrielAzion · May 4, 2026
@@ -1,28 +1,115 @@
 ---
-title: How to generate a Let’s Encrypt certificate using the HTTP-01 challenge for your application via API
+title: How to generate a Let's Encrypt certificate for your application via API
 description: >-
   Discover how you can generate a free TLS certificate issued by Let's Encrypt
   and automatically managed by Azion to secure your application via API.
-meta_tags: "certificate, ssl, tls, let's encrypt, domain"
+meta_tags: "certificate, ssl, tls, let's encrypt, API"
 namespace: documentation_guides_lets_encrypt_via_api
 permalink: /documentation/products/guides/how-to-generate-a-lets-encrypt-certificate-via-api/
 ---
 
+import Tabs from '~/components/tabs/Tabs'
+import Code from '~/components/Code/Code.astro'
+
 Web applications that use the HTTPS protocol require a [Certificate Manager](/en/documentation/products/build/applications/domains/mtls/). When you redirect your traffic to Azion, you have the option to generate a *Let's Encrypt*™ certificate, which is a free and secure way to encrypt data for your application. Azion automates the issuance, renewal, and deactivation of this TLS certificate through an internal certificate management solution.
 
-## Let's Encrypt HTTP-01 Challenge through API
+## Let's Encrypt certificates via API
+
+Azion's API V4 offers issuance and renewal of [Let's Encrypt certificates](/en/documentation/products/secure/firewall/certificate-manager/#lets-encrypt-certificate) using two validation methods:
 
-Azion now offers API-based issuance and renewal of [Let's Encrypt certificates](/en/documentation/products/secure/firewall/certificate-manager/#lets-encrypt-certificate) using the HTTP-01 challenge, providing a streamlined process with no need for DNS TXT records. This offers a straightforward and convenient integration solution, particularly beneficial for customers managing numerous domains and hostnames.
+- **DNS-01**: Validation through a TXT record in the domain's DNS. This method is recommended when you have control over the domain's DNS records, being ideal for wildcard domains (`*`) or when you don't have direct access to the web server.
+- **HTTP-01**: Validation through a file made available on the web server. This method is recommended when you don't have control over DNS records, being simpler for domains already pointing to Azion's infrastructure.
 
-Certificates auto-renew before expiring, removing maintenance windows, and maintaining existing quotas, billing, and permissions. Perfect for ecommerce platforms and hosting providers, this enhancement enables faster onboarding and secures customer sites in minutes without DNS changes.
+Certificates are automatically renewed before expiring, as long as validation configurations are valid and up to date, eliminating maintenance windows and maintaining existing quotas, billing, and permissions.
 
-For more information on these updates, [visit the Certificate Manager documentation](/en/documentation/products/secure/firewall/certificate-manager/#lets-encrypt-certificate).
+For more information on these updates, visit the [Certificate Manager documentation](/en/documentation/products/secure/firewall/certificate-manager/#lets-encrypt-certificate).
 
 ---
 
-### How to issue a Let's Encrypt certificate via HTTP-01 challenge
+## How to issue a Let's Encrypt certificate via API
+
+<Tabs client:visible>
+<Fragment slot="tab.dns01">Challenge DNS-01</Fragment>
+<Fragment slot="tab.http01">Challenge HTTP-01</Fragment>
+
+<Fragment slot="panel.dns01">
+
+### Issuing a certificate via DNS-01
+
+The DNS-01 challenge requires adding a TXT record to the domain's DNS to prove ownership. This method is ideal for wildcard domains or when you prefer to manage validation via DNS.
+
+1. Define the hostname to be used in the digital certificate (for example, `mysite.azion.com`) as `common_name`.
+
+2. Configure the `_acme-challenge` CNAME record in your DNS provider as described in the guide [How to generate a Let's Encrypt certificate for your domain](/en/documentation/products/guides/how-to-generate-a-lets-encrypt-certificate/#option-2-preparing-dns-entry-with-an-external-dns-provider).
+
+3. Create or use an existing API Token (see [Get started with Azion API](/en/documentation/products/overview-azion-api/#prerequisites)).
+
+4. Make a call to request a new certificate with the `"dns"` challenge at the endpoint `https://api.azion.com/v4/digital_certificates/certificates/request`.
+
+For example:
+
+<Code lang="bash" code={`curl --request POST \\
+  --url https://api.azion.com/v4/digital_certificates/certificates/request \\
+  --header 'Accept: application/json' \\
+  --header 'Authorization: Bearer {yourtoken}' \\
+  --header 'Content-Type: application/json' \\
+  --data '{
+  "name": "My certificate",
+  "challenge": "dns",
+  "authority": "lets_encrypt",
+  "common_name": "mysite.azion.com",
+  "alternative_names": []
+}'`}/>
 
-1. Define the hostname to be used in the digital certificate (for example, mysite.azion.com) as `common_name`.
+5. The response will be similar to the one below:
+
+```json
+{
+  "state": "executed",
+  "data": {
+    "id": 127013,
+    "name": "My certificate",
+    "certificate": null,
+    "issuer": null,
+    "subject_name": [
+      "mysite.azion.com"
+    ],
+    "validity": null,
+    "status": "Pending",
+    "type": "edge_certificate",
+    "managed": true,
+    "status_detail": "",
+    "csr": null,
+    "challenge": "dns",
+    "authority": "lets_encrypt",
+    "key_algorithm": "",
+    "active": true,
+    "product_version": "2.0",
+    "last_editor": "{your_user@azion.com}",
+    "last_modified": "2025-06-25T21:32:21.016402Z"
+  }
+}
+```
+
+6. If the resulting status is **Pending**, the request was scheduled successfully.
+
+7. Monitor the issuance status by querying the certificate details at the endpoint `https://api.azion.com/v4/digital_certificates/certificates/{id}`, replacing `{id}` with the identifier provided in the previous response.
+
+   a. In case of failure, an error message will be displayed in the **status_detail** property, such as: `"status_detail": "An error has occurred while issuing the requested certificate. Please verify the following domains CNAME: mysite.azion.com"`
+
+8. If the process was successful, the certificate will be issued and the status will be **Active**.
+
+9. Now you just need to associate your certificate with the desired workload and adjust the TLS/HTTPS properties as needed.
+
+</Fragment>
+
+<Fragment slot="panel.http01">
+
+### Issuing a certificate via HTTP-01
+
+The HTTP-01 challenge provides a streamlined process with no need for DNS TXT records. This offers a straightforward and convenient integration solution, particularly beneficial for customers managing numerous domains and hostnames.
+
+1. Define the hostname to be used in the digital certificate (for example, `mysite.azion.com`) as `common_name`.
 
 2. Ensure that the DNS for this hostname is pointed to Azion (see [How to point your domain to Azion](/en/documentation/products/guides/point-domain-to-azion/)). This must be done in your DNS provider service.
 
@@ -34,20 +121,18 @@ For more information on these updates, [visit the Certificate Manager documentat
 
 For example:
 
-```shell
-curl --request POST \
-  --url https://api.azion.com/v4/digital_certificates/certificates/request \
-  --header 'Accept: application/json' \
-  --header 'Authorization: Bearer {yourtoken}' \
-  --header 'Content-Type: application/json' \
+<Code lang="bash" code={`curl --request POST \\
+  --url https://api.azion.com/v4/digital_certificates/certificates/request \\
+  --header 'Accept: application/json' \\
+  --header 'Authorization: Bearer {yourtoken}' \\
+  --header 'Content-Type: application/json' \\
   --data '{
   "name": "My certificate",
   "challenge": "http",
   "authority": "lets_encrypt",
   "common_name": "mysite.azion.com",
   "alternative_names": []
-}'
-```
+}'`}/>
 
 5. The response will be similar to the one below:
 
@@ -89,6 +174,9 @@ curl --request POST \
 
    a. In case of failure, an error message will be displayed in the **status_detail** property, such as `"status_detail": "An error has occurred while issuing the requested certificate. Please verify the following domains CNAME: mysite.azion.com"`
 
-9. If the process was successful, the certificate will be issued and the status will be **active**.
+9. If the process was successful, the certificate will be issued and the status will be **Active**.
+
+10. Now you just need to associate your certificate with the desired workload and adjust the TLS/HTTPS properties as needed.
 
-10. Now you just need to associate your certificate with the desired workload and adjust the TLS/HTTPS properties as needed.
+</Fragment>
+</Tabs>
@@ -125,10 +125,11 @@ Once you have an application, you need to [create a Workload](/en/documentation/
 4. Under the **Subdomain** and **Domain** fields, add the FQDN of the domain you created in the previous sections. Example: `www.yourdomain.org`.
 5. Under **Applications**, select the application you created.
 6. Under **Digital Certificate**, select the option **Let's Encrypt**.
-7. Choose the validation method:
-    - DNS-01: Add a TXT record to the domain's DNS. This method is recommended for wildcard domains (*) or when you don't have direct control over the web server.
-    - HTTP-01: Validate the domain through a file made available on the web server. This method is simpler for domains already pointing to Azion's infrastructure.
-8. Click the **Save** button.
+7. Click the **Save** button.
+
+:::note
+The certificate will be issued using the **DNS-01** validation method. For domains hosted on Edge DNS, validation is automatic. For domains on external DNS providers, make sure the `_acme-challenge` CNAME record is correctly configured.
+:::
 
 </Fragment>
 
@@ -144,10 +145,11 @@ Once you have an application, you need to [create a domain](/en/documentation/pr
 4. Under **Applications**, select the application you created.
 5. Under **CNAME**, add the FQDN of the domain you created in the previous sections. Example: `www.yourdomain.org`.
 6. Under **Digital Certificate**, select the option **Let's Encrypt**.
-7. Choose the validation method:
-    - DNS-01: Add a TXT record to the domain's DNS. This method is recommended for wildcard domains (*) or when you don't have direct control over the web server.
-    - HTTP-01: Validate the domain through a file made available on the web server. This method is simpler for domains already pointing to Azion's infrastructure.
-8. Click the **Save** button.
+7. Click the **Save** button.
+
+:::note
+The certificate will be issued using the **DNS-01** validation method. For domains hosted on Edge DNS, validation is automatic. For domains on external DNS providers, make sure the `_acme-challenge` CNAME record is correctly configured.
+:::
 </Fragment>
 
 </Tabs>