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

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.

View as Markdown

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.

  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.

  3. Create or use an existing API Token (see Get started with Azion API).

  4. 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": []
}
  1. 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"
}
}

  1. If the resulting status is Pending, the request was scheduled successfully.

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

  3. If the process was successful, the certificate will be issued and the status will be Active.

  4. Now you just need to associate your certificate with the desired workload and adjust the TLS/HTTPS properties as needed.