How to generate a Let's Encrypt certificate for your application via API

Web applications that use the HTTPS protocol require a Certificate Manager. 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 certificates via API

Azion’s API V4 offers issuance and renewal of Let’s Encrypt certificates using two validation methods:

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

How to issue a Let’s Encrypt certificate via API

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.

Define the hostname to be used in the digital certificate (for example, mysite.azion.com) as common_name.
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.
Create or use an existing API Token (see Get started with Azion API).
Make a call to request a new certificate with the "dns" challenge at the endpoint https://api.azion.com/v4/workspace/tls/certificates/request.

For example:

curl --request POST \
--url https://api.azion.com/v4/workspace/tls/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": []
}'

The response will be similar to the one below:

{
  "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"
  }
}

If the resulting status is Pending, the request was scheduled successfully.
Monitor the issuance status by querying the certificate details at the endpoint https://api.azion.com/v4/workspace/tls/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"
If the process was successful, the certificate will be issued and the status will be Active.
Now you just need to associate your certificate with the desired workload and adjust the TLS/HTTPS properties as needed.

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.

Define the hostname to be used in the digital certificate (for example, mysite.azion.com) as common_name.
Ensure that the DNS for this hostname is pointed to Azion (see How to point your domain to Azion). This must be done in your DNS provider service.

a. If you need to issue a single certificate with multiple hostnames (alternative names), all hostnames must be directed to Azion; otherwise, the issuance will fail.
Once the DNS responds correctly, create or use an existing API Token (see Get started with Azion API).
Make a call to request a new certificate with the "http" challenge at the endpoint https://api.azion.com/v4/workspace/tls/certificates/request.

For example:

curl --request POST \
--url https://api.azion.com/v4/workspace/tls/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": []
}'

The response will be similar to the one below:

{
  "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": "http",
    "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"
  }
}

If the resulting status is Pending, the request was scheduled successfully.
The Azion platform will schedule the certificate issuance automatically even if you don’t have a workload with the related hostname published and active on Azion.

a. Azion itself deploys a service that responds to the Let’s Encrypt HTTP-01 challenge and completes it as soon as the issuance is finished.
Monitor the issuance status by querying the certificate details at the endpoint https://api.azion.com/v4/workspace/tls/certificates/{id} replacing {id} with the identifier provided in the previous response, such as "id": 127013.

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"
If the process was successful, the certificate will be issued and the status will be Active.
Now you just need to associate your certificate with the desired workload and adjust the TLS/HTTPS properties as needed.