---
name: azion-request-a-let-s-encrypt-certificate-with-the-api
description: >-
  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.
---

# Request a Let's Encrypt certificate with the API

You can request a TLS certificate signed by Let's Encrypt™ through the [Azion API](/en/documentation/devtools/api/#authentication), validated by the DNS-01 or the HTTP-01 challenge, including a wildcard certificate. To obtain one while you create a [workload](/en/documentation/platform/workloads/) in Azion Console instead, refer to [Certificates](/en/documentation/platform/workloads/certificate-manager/certificates/#lets-encrypt-certificate).

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](/en/documentation/guides/platform/migration/point-domain-to-azion/) |

---

## Prerequisites

- A personal token, sent in the `Authorization` header as `Token [TOKEN VALUE]`. To create one, refer to [Manage a personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/).
- `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-challenge` CNAME record of the hostname, set at that provider. A zone in [Edge DNS](/en/documentation/platform/edge-dns/) needs no record. For the record's name and value, refer to [Domain validation](/en/documentation/platform/workloads/certificate-manager/issuance-and-renewal/#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](/en/documentation/platform/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`:

```bash
curl --request POST \
  --url https://api.azion.com/v4/workspace/tls/certificates/request \
  --header 'Accept: application/json' \
  --header 'Authorization: Token [TOKEN VALUE]' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "example-wildcard",
  "authority": "lets_encrypt",
  "challenge": "dns",
  "common_name": "*.example.com",
  "alternative_names": []
}'
```

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](/en/documentation/platform/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](/en/documentation/platform/workloads/certificate-manager/issuance-and-renewal/#statuses). For the retries Azion makes after a failed attempt, refer to [Issuance time and retries](/en/documentation/platform/workloads/certificate-manager/issuance-and-renewal/#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](/en/documentation/platform/workloads/settings/#tls).

To bind the certificate from Azion Console, the Azion CLI, or the API, refer to [Bind the certificate to the workload](/en/documentation/guides/application-security/tls-and-certificates/how-to-generate-a-lets-encrypt-certificate/#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.

---

## Next steps

- [Certificates](/en/documentation/platform/workloads/certificate-manager/certificates.md): Every field of a Let's Encrypt request, the full status table, and the errors the API returns.
- [Workload settings](/en/documentation/platform/workloads/settings.md#tls): Bind the certificate to the workload that serves the hostname, and set its TLS options.
- [Issuance and renewal](/en/documentation/platform/workloads/certificate-manager/issuance-and-renewal.md): How a certificate moves through its statuses, the retries after a failed issuance, renewal, and wildcard names.
- [Workloads guides and tutorials](/en/documentation/platform/workloads/guides.md): Other tasks for the workloads and the TLS certificates they use.
- [Run multi-tenant SaaS applications](/en/documentation/use-cases/build-and-run-applications/run-multi-tenant-saas-applications.md): Serve every tenant subdomain of a SaaS product under one wildcard certificate.