--- name: azion-upload-a-digital-certificate description: >- Upload a server certificate, or create a CSR for your certificate authority to sign, and bind the certificate to a workload. --- # Upload a digital certificate You can add a certificate that a certificate authority (CA) issued for your domain to [Certificate Manager](/en/documentation/platform/workloads/#certificate-manager) and bind it to a [workload](/en/documentation/platform/workloads/), from Azion Console, the [Azion CLI](/en/documentation/devtools/cli/), or the API. For a certificate that Azion requests from Let's Encrypt and renews, refer to [Request a Let's Encrypt certificate](/en/documentation/guides/application-security/tls-and-certificates/how-to-generate-a-lets-encrypt-certificate/). For the Trusted CA certificate that checks client certificates, refer to [Configure mTLS on a workload](/en/documentation/guides/application-security/tls-and-certificates/associate-an-mtls-certificate/). A server certificate covers the hostnames a workload serves over HTTPS. You get one in either of two ways: you upload a certificate with its private key, or Certificate Manager creates a certificate signing request (CSR) and keeps the private key while your CA signs the certificate. Either way, a workload uses the certificate only once its `tls.certificate` field names it, and the certificate reads `inactive` until then. An account that runs on API v3 with Domains selects the certificate on each domain instead. For more information, refer to [Domains](/en/documentation/platform/workloads/domains/). --- Select an interface. The prerequisites and the steps of each task follow your choice. ## Prerequisites - A workload that lists your domain in its domains. To add the domain, refer to [Add a custom domain to a workload](/en/documentation/guides/platform/migration/configure-a-domain/). - To upload a certificate: the certificate in PEM format and its private key, with no passphrase. RSA 2048 keys and P-256 keys are accepted. - To create a CSR: a domain your account has permission to use. **Console** - Access to Azion Console. For more information, refer to [How to access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). **CLI** - The [Azion CLI](/en/documentation/devtools/cli/), authorized with your account. This page matches Azion CLI 4.23.0. - The workload ID. `azion create workload` prints it as `Created Workload with ID `. **API** - A personal token for the `Authorization` header, in the form `Token [TOKEN VALUE]`. To create a token, refer to [Personal tokens](/en/documentation/fundamentals/personal-tokens/). - `curl` or another HTTP client. - The workload ID. `azion create workload` prints it as `Created Workload with ID `. --- ## Upload a server certificate Certificate Manager stores the certificate with its private key, and it never returns the private key afterward. Intermediate certificates are accepted with the certificate. **Console** To upload the certificate in Azion Console: 1. **Open the Certificate Manager page** Access [Azion Console](https://console.azion.com/) > **Certificate Manager**. 2. **Open the Create Digital Certificate page** 3. **Choose the Server Certificate preset** Select **Server Certificate**. 4. **Name the certificate** In **Name**, enter a name, such as `my-certificate`. 5. **Paste the certificate** In **Certificate**, paste the certificate, including its `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. 6. **Paste the private key** In **Private Key**, paste the private key, including its `-----BEGIN` and `-----END` lines. 7. **Create the certificate** Select **Create**. The certificate appears in **Certificate Manager** as a **TLS Certificate**. **CLI** To upload the certificate with the Azion CLI, pass the certificate file and the private key file: ```bash azion create digital-certificate --name my-certificate --certificate certificate.pem --private-key private-key.pem ``` The command prints the ID of the new certificate: ```text Created Digital Certificate with ID ``` To confirm the upload, list your certificates: ```bash azion list digital-certificate --details ``` This excerpt of the output shows the certificate as `inactive`, because no workload uses it yet: ```text ID NAME STATUS ISSUER VALIDITY TYPE MANAGED ... my-certificate inactive 2026-01-31 12:00:00+00:00 edge_certificate false ... ``` **API** To upload the certificate with the API, send a `POST` request to the certificates endpoint. Write every line break of the certificate and the private key as `\n`, so each value is one continuous JSON string: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/tls/certificates \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-certificate", "certificate": "-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----\n", "private_key": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n" }' ``` The API answers `201` with the new certificate and its `id`. The certificate exists with `type` set to `edge_certificate` and `status` set to `inactive`. A private key the API cannot read is refused with `The provided private key is invalid. Please check the key and try again.` Send the key that matches the certificate, in PEM format and without a passphrase. --- ## Create a certificate signing request A CSR lets your own CA sign the certificate while Certificate Manager generates and keeps the private key. Name the hostnames the workload lists in its domains. The API accepts a certificate whose names do not match those domains, so it does not catch the mismatch for you. **Console** The presets of the **Create Digital Certificate** page do not include a CSR. Create the CSR with the Azion CLI or the API first. To copy the request in Azion Console: 1. **Open the Certificate Manager page** Access [Azion Console](https://console.azion.com/) > **Certificate Manager**. 2. **Open the CSR entry** Select the entry that the CSR created. Its **Edit Digital Certificate** page opens. 3. **Copy the request** In **Certificate Signing Request (CSR)**, select **Copy**. Azion Console shows "Successfully copied!", and the request is ready to submit to your CA. **CLI** To create the CSR with the Azion CLI, pass the hostnames and the details of your organization. `--alternative-names` takes a comma-separated list, and `--key-algorithm` takes `rsa_2048`, `rsa_4096`, or `ecc_384`: ```bash azion create csr --name my-csr \ --common-name example.com \ --alternative-names "www.example.com" \ --country US --state California --locality "San Francisco" \ --organization "Example Corp" --organization-unity IT \ --email admin@example.com \ --key-algorithm rsa_2048 ``` The command creates a certificate entry that holds the request in its `csr` field. The entry reads `pending` until you add the certificate your CA signs. To read the request, find the entry's ID with `azion list digital-certificate --details`, then describe the entry: ```bash azion describe digital-certificate --digital-certificate-id --format json ``` The `csr` field of the output holds the request, with each line break written as `\n`. Convert those to line feeds before you submit the request to your CA. **API** To create the CSR with the API, send a `POST` request to the CSR endpoint. `key_algorithm` takes `rsa_2048`, `rsa_4096`, or `ecc_384`: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/tls/csr \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-csr", "common_name": "example.com", "alternative_names": ["www.example.com"], "country": "US", "state": "California", "locality": "San Francisco", "organization": "Example Corp", "organization_unity": "IT", "email": "admin@example.com", "key_algorithm": "rsa_2048" }' ``` The API answers `201` with the new certificate entry and its `id`. The `csr` field of the entry holds the request, with each line break written as `\n`. Convert those to line feeds before you submit the request to your CA. The entry reads `pending` until you add the signed certificate. A request that names a hostname in a domain your account has no permission for is refused with `This account cannot use certain common or alternative names because it does not have permission for their domain names.` For the meaning of each CSR field, refer to [Certificates](/en/documentation/platform/workloads/certificate-manager/certificates/#certificate-signing-requests). Submit the request to the CA of your choice, such as DigiCert, GlobalSign, or IdenTrust. The CA validates the details in the request and, once it approves them, issues the signed certificate. --- ## Add the signed certificate to the CSR entry The certificate your CA signs completes the entry that the certificate signing request (CSR) created. Add it in Azion Console or with the API, in PEM format, including its `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. **Console** To add the signed certificate in Azion Console: 1. **Open the Certificate Manager page** Access [Azion Console](https://console.azion.com/) > **Certificate Manager**. 2. **Open the CSR entry** Select the entry that the CSR created. Its **Edit Digital Certificate** page opens. 3. **Paste the signed certificate** In **Certificate**, paste the certificate your CA signed. 4. **Save the entry** Select **Save**. The entry holds the signed certificate, and you can bind it to a workload. **API** To add the signed certificate with the API, send a `PATCH` request to the entry, with the certificate in `certificate`. Write every line break as `\n`: ```bash curl --request PATCH \ --url https://api.azion.com/v4/workspace/tls/certificates/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "certificate": "-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----\n" }' ``` The API answers `200`. The entry holds the signed certificate, and you can bind it to a workload. --- ## Bind the certificate to the workload A workload uses a server certificate once its `tls.certificate` field holds the certificate's ID. From that update on, the certificate reads `active`. Make sure the certificate covers the hostnames the workload lists in its domains: the API accepts a certificate whose names do not match them. **Console** To bind the certificate in Azion Console: 1. **Open the Workloads page** Access [Azion Console](https://console.azion.com/) > **Workloads**. 2. **Open the workload** Select the workload that lists your domain. Its edit form opens. 3. **Turn on HTTPS support** In **Protocol Settings**, turn on **HTTPS support** if it is off. 4. **Select the certificate** In **Digital Certificate**, select your certificate in the **My certificates** group. 5. **Save the workload** Select **Save**. Azion Console shows "Your workload has been updated". **CLI** To bind the certificate with the Azion CLI, save a JSON file with the workload ID and the `tls` object, here as `tls.json`. Keep `ciphers` and `minimum_version` at the values the workload already holds. This example shows the defaults of a new workload: ```json { "id": , "tls": { "certificate": , "ciphers": 7, "minimum_version": "tls_1_3" } } ``` Update the workload with the file: ```bash azion update workload --file tls.json ``` The command prints the ID of the workload it updated: ```text Updated Workload with ID ``` To confirm the binding, list your certificates: ```bash azion list digital-certificate --details ``` This excerpt of the output shows the certificate as `active`: ```text ID NAME STATUS ISSUER VALIDITY TYPE MANAGED ... my-certificate active 2026-01-31 12:00:00+00:00 edge_certificate false ... ``` **API** To bind the certificate with the API, send a `PATCH` request to the workload with the `tls` object. Keep `ciphers` and `minimum_version` at the values the workload already holds. This example shows the defaults of a new workload: ```bash curl --request PATCH \ --url https://api.azion.com/v4/workspace/workloads/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "tls": { "certificate": , "ciphers": 7, "minimum_version": "tls_1_3" } }' ``` The API accepts the update, and the workload then names the certificate in `tls.certificate`. A Trusted CA certificate in `tls.certificate` is refused with `Invalid certificate type, MUST be an Edge Certificate.` To go back to Azion's own certificate, select *Azion (SAN)* in **Digital Certificate**, or send `null` in `tls.certificate`. Binding a certificate is a workload change, which takes several minutes to reach all of Azion's distributed infrastructure. Requests can receive the old or the new configuration meanwhile. For certificate errors and their fixes, refer to [Troubleshoot Workloads](/en/documentation/platform/workloads/troubleshooting/#certificate-manager). --- ## Replace a certificate before it expires A certificate you upload does not renew itself, and once its `validity` date passes, it no longer protects traffic. To replace it, upload the new certificate as Upload a server certificate describes, then bind it as Bind the certificate to the workload describes. The old entry reads `inactive` once no workload names it. Delete it after the new certificate is `active` and the change has propagated. For why to switch while the old certificate is still valid, refer to [Workloads best practices](/en/documentation/platform/workloads/best-practices/#certificate-manager). --- ## Next steps - [Request a Let's Encrypt certificate](/en/documentation/guides/application-security/tls-and-certificates/how-to-generate-a-lets-encrypt-certificate.md): Have Azion request and renew a certificate for your domain instead of uploading one. - [Configure mTLS on a workload](/en/documentation/guides/application-security/tls-and-certificates/associate-an-mtls-certificate.md): Upload a Trusted CA certificate and require client certificates on the workload. - [Certificates](/en/documentation/platform/workloads/certificate-manager/certificates.md): Look up certificate fields, key algorithms, statuses, and the errors the API returns. - [Troubleshoot Workloads](/en/documentation/platform/workloads/troubleshooting.md): Find the cause of a certificate error and the fix for it.