# Certificates [Certificate Manager](/en/documentation/platform/workloads/#certificate-manager) stores the X.509 certificates a [workload](/en/documentation/platform/workloads/) uses for TLS. A server certificate is one you upload or one Azion requests from Let's Encrypt, and a Trusted CA certificate verifies client certificates for mutual TLS (mTLS). Certificate Manager also creates certificate signing requests (CSRs) and stores certificate revocation lists (CRLs). This page lists every field of these objects by its API name. For how Azion validates, issues, and renews a Let's Encrypt certificate, refer to [Issuance and renewal](/en/documentation/platform/workloads/certificate-manager/issuance-and-renewal/). --- ## Interfaces Four interfaces manage certificates, CSRs, and CRLs. The tables on this page name the Console control, the API field, and the CLI flag of each field. | Interface | Create | Read, update, delete | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Azion Console](https://console.azion.com/) | The **Certificate Manager** menu, then the **Create Digital Certificate** page at `/digital-certificates/create`, with the presets **Server Certificate**, **Trusted CA Certificate**, *New Let's Encrypt Certificate (HTTP-01)*, and *New Let's Encrypt Certificate (DNS-01)* | The **Edit Digital Certificate** page edits a certificate, and the **Edit CRL** page edits a CRL | | Azion API v4 | `POST /v4/workspace/tls/certificates` uploads a certificate; `POST /v4/workspace/tls/certificates/request` requests a Let's Encrypt certificate; `POST /v4/workspace/tls/csr` creates a CSR; `POST /v4/workspace/tls/crls` stores a CRL | `GET`, `PUT`, `PATCH`, and `DELETE` on `/v4/workspace/tls/certificates/{certificate_id}` and on `/v4/workspace/tls/crls/{crl_id}`. `GET /v4/workspace/tls/certificates` and `GET /v4/workspace/tls/crls` list them | | Azion CLI | [`azion create digital-certificate`](/en/documentation/devtools/cli/resources/), `azion create csr`, and `azion create crl` | `azion list digital-certificate`, `azion describe digital-certificate`, `azion list crl`, and `azion describe crl` | | [Terraform](/en/documentation/devtools/terraform/certificates/) | The certificate resources that page lists | The same resources | A workload uses a certificate only once you bind the certificate to the workload. A server certificate goes in the workload's `tls.certificate` field, and a Trusted CA certificate in `mtls.config.certificate`. In the Console, the workload's **Digital Certificate** field lists a group **Certificates presets** and a group **My certificates**, which holds the account's certificates. For every workload field, refer to [Workload settings](/en/documentation/platform/workloads/settings/). --- ## Certificate types A workload can use three kinds of certificate. Certificate Manager stores two of them, told apart by `type`, which is fixed once the certificate exists. The third is Azion's own certificate, which you never store. | Kind | `type` value | Console names | Workload field | Private key | | ------------------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------ | | Server certificate, uploaded or requested from Let's Encrypt | `edge_certificate` | **Server Certificate** preset, **TLS Certificate** in the list, **Update a Server Certificate** on the edit page | `tls.certificate` | Required on upload | | Trusted CA certificate | `trusted_ca_certificate` | **Trusted CA Certificate** preset and list entry, **Update Trusted CA Certificate** on the edit page | `mtls.config.certificate` | Not required | | Azion SAN certificate | none, Azion holds it | *Azion (SAN)* preset in the workload's **Digital Certificate** field | `tls.certificate` set to `null` | None to send | ### Azion SAN certificate The Azion SAN certificate is Azion's own TLS certificate, and a workload uses it when `tls.certificate` is `null`. In the workload form, *Azion (SAN)* sets that value. The certificate lists the hostnames Azion assigns as Subject Alternative Names (SANs): the workload domain in the `azionedge.net` zone, and the Azion Custom Domain under `azion.app`. It costs nothing extra and needs no upload. For example, a test workload reached only on `.map.azionedge.net` serves HTTPS with the Azion SAN certificate and nothing to manage. The `azionedge.net` zone is shared with other Azion customers, so a hostname in a domain of your own needs a server certificate. ### Server certificate A server certificate is a TLS certificate for your own domains, stored with `type` set to `edge_certificate`. You upload one that a certificate authority (CA) issued to you, with its private key, at no additional cost. Or you ask Azion to request one from Let's Encrypt, described in Let's Encrypt certificate. A certificate for a single domain and a certificate for several hostnames listed as SANs are both accepted. The API does not compare those names with the workload's domains: a certificate whose names do not match them is accepted. Domains served with an uploaded certificate use the Server Name Indication (SNI) extension of TLS. Azion follows NIST recommendations when it stores and processes certificates. Once saved, the private key cannot be read back from the Console or the API. The edit page reads "Paste the PEM-encoded TLS X.509 certificate and private key in the respective fields to update the certificate. The current certificate and private key are hidden to protect sensitive information." To replace a server certificate without downtime, refer to [Workloads best practices](/en/documentation/platform/workloads/best-practices/#certificate-manager). ### Validation levels The CA that issues a certificate you upload validates the request at one of three levels, which you choose when you obtain the certificate: | Level | What the CA validates | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Domain Validation (DV) | Your right to use the domain. The simplest of the three. | | Organization Validation (OV) | Your right to use the domain, plus further checks on the requesting organization. | | Extended Validation (EV) | Documents that prove the physical, legal, and operational existence of the requesting organization. The most complex of the three. | ### Let's Encrypt certificate A Let's Encrypt certificate is a server certificate that Azion requests from the Let's Encrypt CA and renews for you. The API returns it with `managed` set to `true`, `authority` set to `lets_encrypt`, and `challenge` set to `dns` or `http`. The challenge is the ACME check that proves you control the names on the certificate. You request one from the *New Let's Encrypt Certificate (DNS-01)* or *New Let's Encrypt Certificate (HTTP-01)* preset, or with `POST /v4/workspace/tls/certificates/request`. The presets appear in Certificate Manager and in the workload's **Digital Certificate** field. From the workload form, the Console names the certificate `Lets Encrypt - - `. It sets `key_algorithm` to `rsa_2048` and takes `common_name` and `alternative_names` from the workload's **Domains**. The edit page of a managed certificate reads "This is a Let's Encrypt™ certificate automatically created and managed by Azion." A wildcard certificate, such as one for `*.example.com`, is issued through the DNS-01 challenge. Every name on the request must belong to a domain the account has permission for, or the request is refused, as Errors lists. For the challenges, the renewal schedule, and wildcard names, refer to [Issuance and renewal](/en/documentation/platform/workloads/certificate-manager/issuance-and-renewal/). ### Trusted CA certificate A Trusted CA certificate is the certificate of a CA you trust to sign client certificates. A workload with mTLS turned on checks each client certificate against the Trusted CA certificate in its `mtls.config.certificate` field. Upload the CA certificate with `type` set to `trusted_ca_certificate`, and include intermediate certificates when your chain has them. It takes no private key. The edit page reads "Paste the PEM-encoded Trusted CA certificate in the respective field to update the certificate. The current certificate is hidden to protect sensitive information." For how the enforce and permissive modes treat a client certificate, refer to [mTLS](/en/documentation/platform/workloads/mtls/). --- ## Certificate fields A certificate carries fields you set and fields Azion fills. An upload sends `name`, `type`, `certificate`, and `private_key`, and a Trusted CA certificate leaves out `private_key`. A Let's Encrypt request sends `name`, `authority`, `challenge`, and `common_name`, which the API requires, plus the optional `alternative_names` and `key_algorithm`. | Console control | API field | Type | Values | Default | CLI flag | | --------------------------------------------------------------- | ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------- | | **Name** | `name` | string | 1 to 250 characters | required, no default | `--name` | | The preset chosen on **Create Digital Certificate** | `type` | enum | `edge_certificate`, `trusted_ca_certificate`; fixed after creation | `edge_certificate` when `--certificate-type` is left out | `--certificate-type` | | **Certificate** | `certificate` | string, or `null` | a PEM certificate, up to 1,000,000 characters | none | `--certificate`, the path to a PEM file | | **Private Key** | `private_key` | string, write-only, or `null` | a PEM private key, up to 64,000 characters | none | `--private-key`, the path to a PEM file | | none | `active` | boolean | `true`, `false` | `true` | none on `create` | | The *New Let's Encrypt Certificate* presets | `authority` | enum | `lets_encrypt` | required on a request | `--authority` | | The *New Let's Encrypt Certificate* presets | `challenge` | enum | `dns` for DNS-01, `http` for HTTP-01 | required on a request | `--challenge` | | The workload's **Domains**, on a request from the workload form | `common_name` | string, write-only | the main hostname, 1 to 64 characters | required on a request | `--common-name` | | The workload's **Domains**, on a request from the workload form | `alternative_names` | array of string, write-only | other hostnames, 1 to 250 characters each | none | `--alternative-names`, comma-separated | | none | `key_algorithm` | enum | `rsa_2048` (2048-bit RSA), `rsa_4096` (4096-bit RSA), `ecc_384` (384-bit prime field curve) | `ecc_384` on an API request; `rsa_2048` from the workload form | `--key-algorithm` | Azion fills the fields below, and no request can set them: | API field | Type | What it holds | | ----------------- | ---------------------------- | ------------------------------------------------------------------------------- | | `id` | integer | The certificate ID, assigned by Azion | | `status` | enum | The state of the certificate, as Statuses describes | | `status_detail` | string, 0 to 500 characters | Why issuance failed; empty (`""`) otherwise | | `managed` | boolean | `true` for a Let's Encrypt certificate that Azion manages, `false` otherwise | | `key_algorithm` | string | On an uploaded certificate, the algorithm of its key, such as `rsa_2048` | | `issuer` | string, or `null` | The CA that issued the certificate | | `subject_name` | array of string | The names the CA confirmed for the certificate | | `validity` | string | The expiration date, such as `2026-01-31 12:00:00+00:00` | | `csr` | string, or `null` | The CSR of a certificate created from one, with each line break written as `\n` | | `renewed_at` | string, date-time, or `null` | When Azion last renewed a managed certificate | | `last_editor` | string | The email of the last user who changed the certificate | | `created_at` | string, date-time | When the certificate was created | | `last_modified` | string, date-time | When the certificate content last changed | | `product_version` | string | `2.0` | An uploaded certificate reads back `authority` and `challenge` as empty strings, and no response carries `private_key`. Upload a server certificate and its private key with the CLI: ```bash azion create digital-certificate --name my-certificate --certificate server.pem --private-key server.key ``` The command prints the ID of the new certificate: ```text Created Digital Certificate with ID ``` Upload a Trusted CA certificate, which takes no private key: ```bash azion create digital-certificate --name my-trusted-ca --certificate ca.pem --certificate-type trusted_ca_certificate ``` The command prints the ID of the new certificate: ```text Created Digital Certificate with ID ``` `azion describe digital-certificate --digital-certificate-id --format json` returns the certificate as the API stores it. The server certificate below is bound to a workload, so its `status` is `active`: ```json { "active": true, "authority": "", "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n", "challenge": "", "created_at": "2026-01-01T12:00:00.000000Z", "csr": null, "id": , "issuer": "", "key_algorithm": "rsa_2048", "last_editor": "", "last_modified": "2026-01-01T12:00:00.000000Z", "managed": false, "name": "my-certificate", "product_version": "2.0", "renewed_at": null, "status": "active", "status_detail": "", "subject_name": [], "type": "edge_certificate", "validity": "2026-01-31 12:00:00+00:00" } ``` --- ## Statuses The read-only `status` field reports the state of a certificate. The API returns one of six values: | Value | Meaning | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `active` | In use. A workload names the certificate in `tls.certificate` or in `mtls.config.certificate`. | | `inactive` | Not in use. No workload names the certificate, and an uploaded certificate starts here. | | `pending` | Azion is processing issuance or renewal, or retrying it. A certificate created from a CSR stays here until the signed certificate is added. | | `challenge_verification` | A Let's Encrypt certificate waits for its DNS-01 or HTTP-01 challenge to validate. | | `failed` | Validation failed, and `status_detail` explains why. | | `expired` | The `validity` date has passed, and the certificate no longer protects traffic. | The Console list shows a warning icon for a `pending` certificate and an error icon for a `failed` one, with `status_detail` as the explanation. A certificate whose `validity` date has passed carries the tag **Expired**. The workload's **Digital Certificate** field warns "This certificate is pending validation and HTTPS may not work until it’s validated" or "This digital certificate failed and HTTPS cannot be used until the issue is resolved". An uploaded certificate reads `inactive` until a workload update names it, and `active` from that update on. Binding a certificate is a change to the workload, which takes several minutes to reach all of Azion's distributed infrastructure, and requests can meet the old or the new configuration meanwhile. For how a Let's Encrypt certificate moves through `pending`, `challenge_verification`, and `active`, refer to [Issuance and renewal](/en/documentation/platform/workloads/certificate-manager/issuance-and-renewal/). `azion list digital-certificate --details` shows the status of each certificate. Here a Trusted CA certificate and a server certificate are bound to a workload, and a second server certificate is not: ```text ID NAME STATUS ISSUER VALIDITY TYPE MANAGED ... my-trusted-ca active 2026-01-31 12:00:00+00:00 trusted_ca_certificate false ... my-certificate active 2026-01-31 12:00:00+00:00 edge_certificate false ... my-certificate-p256 inactive 2026-01-31 12:00:00+00:00 edge_certificate false ... ``` --- ## Key algorithms and formats Certificate Manager reads certificates, private keys, and CRLs in ASCII Privacy Enhanced Mail (PEM) format, with the `-----BEGIN` and `-----END` lines included. A file in any other format is refused. The private key cannot be protected by a passphrase. The header line of the private key depends on its algorithm: | Key | Accepted header lines | | ----- | ------------------------------------------------------------------ | | RSA | `-----BEGIN RSA PRIVATE KEY-----` or `-----BEGIN PRIVATE KEY-----` | | ECDSA | `-----BEGIN EC PRIVATE KEY-----` or `-----BEGIN PRIVATE KEY-----` | An uploaded certificate can use an RSA key or an elliptic curve (ECC/ECDSA) key. An RSA 2048 key in the `-----BEGIN PRIVATE KEY-----` form is accepted, and so is a P-256 key in either form, SEC1 (`-----BEGIN EC PRIVATE KEY-----`) or PKCS#8 (`-----BEGIN PRIVATE KEY-----`). The API then reports the key's algorithm in the read-only `key_algorithm`. For a key that Azion generates, `key_algorithm` takes `rsa_2048`, `rsa_4096`, or `ecc_384`, and the default depends on what generates it: | Object | Default `key_algorithm` | | ----------------------------------------------------------------------------- | ----------------------- | | A Let's Encrypt request through `POST /v4/workspace/tls/certificates/request` | `ecc_384` | | A Let's Encrypt request from the workload form | `rsa_2048` | | A CSR | `rsa_2048` | In an API request body, `certificate`, `private_key`, and `crl` are JSON strings. Send each one as a single continuous string that keeps its `-----BEGIN` and `-----END` lines and writes every line break as `\n`. The CLI reads the same values from PEM files, such as `certificate.pem`, instead. ### Certificate chain When you upload a server certificate, Azion validates its chain and registers the certificate with the full chain. You can also send the full chain yourself, and the Console help text for **Certificate** reads "Intermediate certificates are accepted." A Trusted CA certificate upload accepts intermediate certificates as well. Some older clients cannot validate a chain. The Let's Encrypt chain cross-signed by IdenTrust is expired, so devices that depend on it, mainly Android versions older than 7.1, reject certificates that use it: - If your Let's Encrypt certificate uses the IdenTrust chain, move to a Let's Encrypt chain without that cross-signature, or to a server certificate you upload. - If you use another kind of Let's Encrypt certificate, no action is needed: the failure comes from an outdated certificate chain stored on the device. - If Azion manages your Let's Encrypt certificate, Azion updates the certificate automatically. An affected device still needs its trusted CAs updated. --- ## Certificate signing requests A certificate signing request (CSR) is the request you submit to a CA to obtain your own certificate. Certificate Manager creates the CSR and generates its private key with the algorithm in `key_algorithm`. Azion keeps that key, and the API never returns it. `POST /v4/workspace/tls/csr` and `azion create csr` take these fields: | API field | Type | Values | Required | CLI flag | | -------------------- | --------------- | --------------------------------------------------------------------------------------------------------- | ---------------------- | -------------------------------------- | | `name` | string | 1 to 250 characters | yes | `--name` | | `common_name` | string | the main hostname of the certificate, in fully qualified form, such as `example.com`; 1 to 250 characters | yes | `--common-name` | | `alternative_names` | array of string | other hostnames to register as SANs, 1 to 250 characters each | no | `--alternative-names`, comma-separated | | `country` | string | the two-letter ISO 3166 code of your organization's country, such as `BR` | yes | `--country` | | `state` | string | the state or province of your organization, 1 to 250 characters | yes | `--state` | | `locality` | string | the city or locality of your organization, 1 to 250 characters | yes | `--locality` | | `organization` | string | the name of your organization, 1 to 250 characters | yes | `--organization` | | `organization_unity` | string | the department or unit responsible for the certificate, 1 to 250 characters | yes | `--organization-unity` | | `email` | string, email | the email of the unit responsible for the certificate | yes | `--email` | | `key_algorithm` | enum | `rsa_2048`, `rsa_4096`, `ecc_384` | no, default `rsa_2048` | `--key-algorithm` | The CSR creates a certificate entry with no certificate yet. Its `csr` field holds the request, with each line break written as `\n`, so convert those to line feeds before you submit it to a CA. The entry reads `pending` until you add the certificate the CA signs. On the **Edit Digital Certificate** page, the **Certificate Signing Request (CSR)** field shows the request with a **Copy** button. Its help text reads "Submit the CSR to a certificate authority. Once the certificate is signed, paste the PEM-encoded certificate in the respective field." Through the API, send the signed certificate in `certificate` with `PATCH /v4/workspace/tls/certificates/{certificate_id}`. Every name in `common_name` and `alternative_names` must belong to a domain the account has permission for. For example, the command below names a domain the account has no permission for: ```bash azion create csr --name my-csr --common-name example.org --country BR --state "Rio Grande do Sul" --locality "Porto Alegre" --organization "Example Org" --organization-unity "IT" --email admin@example.org ``` The API refuses it, and the CLI prints: ```text Error: Failed to create the Certificate Signing Request: ["This account cannot use certain common or alternative names because it does not have permission for their domain names."]. Check your settings and try again. If the error persists, contact Azion support ``` --- ## Certificate revocation lists A certificate revocation list (CRL) is the list of certificates a CA revoked before their expiration date, signed by that CA. Certificate Manager stores CRLs, and a workload with mTLS turned on names up to 100 of them in `mtls.config.crl`. For how a workload uses its CRLs, refer to [mTLS](/en/documentation/platform/workloads/mtls/). | Console control | API field | Type | Values | Default | CLI flag | | --------------- | --------- | ------- | -------------------------------------- | -------------------- | ------------------------------- | | **Name** | `name` | string | 1 to 250 characters | required, no default | `--name` | | **CRL** | `crl` | string | a PEM CRL, up to 30,720,000 characters | required, no default | `--crl`, the path to a PEM file | | none | `issuer` | string | the name of the CA that issued the CRL | none | `--issuer` | | none | `active` | boolean | `true`; it cannot be set to `false` | `true` | `--active` | Azion fills the fields below from the CRL itself and from the request: | API field | Type | What it holds | | ----------------- | ----------------- | -------------------------------------------------------- | | `id` | integer | The CRL ID, assigned by Azion | | `last_update` | string, date-time | When the issuer last updated the CRL, read from the CRL | | `next_update` | string, date-time | When the issuer plans the next update, read from the CRL | | `last_editor` | string | The email of the last user who changed the CRL | | `created_at` | string, date-time | When the CRL was stored | | `last_modified` | string, date-time | When the CRL content last changed | | `product_version` | string | `1.0` | Azion validates a CRL before it stores it. Each request stores one CRL, so to add several, send one `POST /v4/workspace/tls/crls` per CRL. A CRL that a workload names in `mtls.config.crl` cannot be deleted: remove it from the workload first. The **Edit CRL** page reads "Paste the PEM-encoded CRL in the respective field to update the certificate. The current certificate is hidden to protect sensitive information." Store a CRL with the CLI: ```bash azion create crl --name my-crl --issuer "My CA" --crl ca.crl ``` The command prints the ID of the new CRL: ```text Created Certificate Revocation List with ID ``` `azion describe crl --crl-id --format json` returns the CRL as the API stores it: ```json { "active": true, "created_at": "2026-01-01T12:00:00.000000Z", "crl": "-----BEGIN X509 CRL-----\n...\n-----END X509 CRL-----", "id": , "issuer": "My CA", "last_editor": "", "last_modified": "2026-01-01T12:00:00.000000Z", "last_update": "2026-01-01T12:00:00Z", "name": "my-crl", "next_update": "2026-01-31T12:00:00Z", "product_version": "1.0" } ``` --- ## Errors The API refuses each request below with the message in the first column. The CLI prints the message inside `Error: Failed to create the Digital Certificate: [...]`, `Error: Failed to request the Digital Certificate: [...]`, `Error: Failed to create the Certificate Signing Request: [...]`, or `Error: Failed to update the Workload: [...]`. The message is followed by `Check your settings and try again. If the error persists, contact Azion support`. For symptoms that return no message, refer to [Workloads troubleshooting](/en/documentation/platform/workloads/troubleshooting/#certificate-manager). | Message | Cause | What to do | | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `The provided private key is invalid. Please check the key and try again.` | The API cannot read the `private_key` sent with the certificate. | Send the private key that matches the certificate, in PEM and without a passphrase. RSA 2048 keys, and P-256 keys in SEC1 or PKCS#8 form, are accepted. | | `This account cannot use certain common or alternative names because it does not have permission for their domain names.` | A Let's Encrypt request or a CSR names a hostname in a domain the account has no permission for. An `azion.app` hostname is refused too, even one a workload of the account holds. | Name only hostnames in domains your account has permission for. | | `Invalid certificate type, MUST be an Edge Certificate.` | A workload's `tls.certificate` holds the ID of a Trusted CA certificate. | Send the ID of a certificate of type `edge_certificate`, or `null` for the Azion SAN certificate. | | `Invalid certificate type, MUST be a Trusted CA.` | A workload's `mtls.config.certificate` holds the ID of a server certificate. | Send the ID of a certificate of type `trusted_ca_certificate`. | Let's Encrypt™ is a trademark of the Internet Security Research Group. All rights reserved. --- ## Related resources - [Issuance and renewal](/en/documentation/platform/workloads/certificate-manager/issuance-and-renewal.md): How Azion validates, issues, and renews a Let's Encrypt certificate, with what each challenge needs. - [mTLS](/en/documentation/platform/workloads/mtls.md): How a workload checks client certificates against a Trusted CA certificate and its CRLs, in enforce and permissive mode. - [Upload a digital certificate](/en/documentation/guides/application-security/tls-and-certificates/digital-certificates.md): The steps to upload a server certificate and bind it to a workload. - [Workloads limits](/en/documentation/platform/workloads/limits.md#certificate-manager): How many certificates an account holds, beside the other bounds on workloads.