Request a Let's Encrypt certificate with the API
Issue a TLS certificate signed by Let's Encrypt through the Azion API with the DNS-01 or HTTP-01 challenge, then check its issuance status.
You can request a TLS certificate signed by Let’s Encrypt™ through the Azion API, validated by the DNS-01 or the HTTP-01 challenge, including a wildcard certificate. To obtain one while you create a workload in Azion Console instead, refer to Certificates.
A web application served over HTTPS needs a TLS certificate. Let’s Encrypt issues one free of charge, and Azion automates its issuance, its renewal, and its deactivation. Azion renews the certificate before it expires, as long as its validation settings stay valid and up to date. The renewal needs no maintenance window, and the certificate keeps its quotas, billing, and permissions.
The two challenges prove control of the hostname in different ways:
| Challenge | challenge value | How Let’s Encrypt validates the hostname | Use it when |
|---|---|---|---|
| DNS-01 | dns | A TXT record in the DNS of the domain | You control the DNS records of the domain, the certificate covers a wildcard domain, or you have no direct access to the web server |
| HTTP-01 | http | A file served for the hostname, answered by a service that Azion runs | You do not control the DNS records, and the domain already points to Azion |
Prerequisites
- A personal token, sent in the
Authorizationheader asToken [TOKEN VALUE]. To create one, refer to Manage a personal token. curl, or another HTTP client.- The hostname the certificate covers, such as
www.example.com. - For DNS-01 with a zone that another DNS provider hosts, the
_acme-challengeCNAME record of the hostname, set at that provider. A zone in Edge DNS needs no record. For the record’s name and value, refer to Domain validation. - For HTTP-01, the DNS of the hostname, and of every alternative name, pointed to Azion.
- For a wildcard certificate, the domain’s zone configured and active in Edge DNS.
Request a certificate with the DNS-01 challenge
With DNS-01, Let’s Encrypt validates the hostname through a TXT record in the DNS of the domain. When the zone is in Edge DNS, Azion inserts the TXT record, and you set nothing. When another DNS provider hosts the zone, set the _acme-challenge CNAME record of the hostname there before you send the request.
To request the certificate, send a POST request to https://api.azion.com/v4/workspace/tls/certificates/request. Its JSON body carries these fields:
| Field | Required | Value |
|---|---|---|
name | Yes | A name for the certificate, such as My certificate |
challenge | Yes | dns |
authority | Yes | lets_encrypt |
common_name | Yes | The hostname the certificate covers, such as www.example.com |
alternative_names | No | The other hostnames the certificate covers, or an empty list, [] |
key_algorithm | No | rsa_2048, rsa_4096, or ecc_384; ecc_384 when left out |
The API accepts the request and returns the new certificate with its id and a pending status. A pending status means that Azion scheduled the issuance. The id identifies the certificate when you check its status.
Request a wildcard certificate
A wildcard name, such as *.example.com, lets one certificate cover the subdomains under it, which you do not list one by one. Azion issues a wildcard certificate only through the DNS-01 challenge. When the domain’s zone is configured and active in Edge DNS, Azion inserts the _acme-challenge TXT record into the zone, and it issues and renews the certificate with no action from you. When the zone is not active in Edge DNS, the validation must be performed by hand.
The request goes through the API because a workload cannot request a wildcard name. Its domains refuse a wildcard entry with The domain does not conform to the format defined in RFC 1035., and the workload form requests a certificate for those domains.
To request the certificate, send the DNS-01 request with the wildcard name in common_name:
The API returns the certificate in data, with its id and status set to pending. A certificate can carry the wildcard name alone or next to specific names in alternative_names. A subdomain that the wildcard covers, such as blog.example.com, needs no entry of its own.
The certificate covers the subdomains, but the workload that serves them still lists each one in full in its domains, up to 50 domains per workload. For that bound, and how to raise it, refer to Workloads limits. To use the certificate, check its status, then bind it to that workload, as the next sections describe.
Request a certificate with the HTTP-01 challenge
With HTTP-01, Let’s Encrypt validates the hostname through a file served for it. The DNS of the domain needs no TXT record. Azion runs the service that answers the HTTP-01 challenge, and it completes the challenge once the issuance finishes. This challenge suits an account that manages many domains and hostnames.
The hostname must point to Azion before you send the request. When the certificate carries alternative names, every one of them must point to Azion, or the issuance fails. Azion schedules the issuance even when no workload with the hostname is published and active.
To request the certificate, send a POST request to https://api.azion.com/v4/workspace/tls/certificates/request. Its JSON body carries these fields:
| Field | Required | Value |
|---|---|---|
name | Yes | A name for the certificate, such as My certificate |
challenge | Yes | http |
authority | Yes | lets_encrypt |
common_name | Yes | The hostname the certificate covers, such as www.example.com |
alternative_names | No | The other hostnames the certificate covers, or an empty list, [] |
key_algorithm | No | rsa_2048, rsa_4096, or ecc_384; ecc_384 when left out |
The API accepts the request and returns the new certificate with its id and a pending status. A pending status means that Azion scheduled the issuance. The id identifies the certificate when you check its status.
Check the issuance status
After a certificate request, Azion validates the hostname and issues the certificate. To see where the issuance stands, send a GET request to https://api.azion.com/v4/workspace/tls/certificates/<certificate-id>, with the id that the request returned. The response returns the certificate with its current status.
Send the request again until the status shows that the issuance finished. When the issuance fails, the status_detail field carries the reason, such as An error has occurred while issuing the requested certificate. Please verify the following domains CNAME: www.example.com.
For what each status means, refer to Statuses. For the retries Azion makes after a failed attempt, refer to Issuance time and retries.
The status and status_detail fields now tell you whether Azion issued the certificate, or why it could not.
Use the certificate on a workload
A certificate protects HTTPS traffic once a workload uses it. Bind the issued certificate to the workload that serves the hostname: its id goes in the workload’s tls.certificate field. Then adjust the TLS and HTTPS settings of that workload as your application needs. For the certificate and protocol settings of a workload, refer to Workload settings.
To bind the certificate from Azion Console, the Azion CLI, or the API, refer to Bind the certificate to the workload. In Azion Console, the certificate appears under My certificates in the workload’s Digital Certificate field, which shows while HTTPS support is on. Once the certificate is issued and the binding propagates, the certificate reads active, and Azion renews it before it expires.