Certificate Manager quickstart

Upload your first certificate to Certificate Manager, bind it to a workload, and confirm the platform marks it active.

Last updated

View as Markdown Agent setup

This guide instructs you through binding your first certificate of your own to a workload with Certificate Manager.

  • Upload a server certificate and its private key to Certificate Manager.
  • Bind the certificate to your workload.
  • Confirm that Certificate Manager reports the certificate as active.

Three objects take part, and each one links to the next:

  1. The certificate is a server certificate you upload to Certificate Manager with its private key. The API stores it with type set to edge_certificate. Its status stays inactive until a workload uses it.
  2. The workload names the certificate in its tls.certificate field. While that field is null, the workload uses the Azion SAN certificate instead.
  3. The domains of the workload are the hostnames the certificate must cover. The API does not compare the certificate’s names with the domains, so a certificate that does not cover them is still accepted.

An uploaded certificate protects no traffic until a workload names it. A workload with no certificate of yours keeps the Azion SAN certificate, which covers only the workload domain and the Azion Custom Domain. This guide changes only the tls settings of the workload and keeps its domains, ports, and deployment as they are.

To have Azion request a certificate from Let’s Encrypt and renew it for you instead, refer to Request a Let’s Encrypt certificate. The workload’s Digital Certificate field also offers the Let’s Encrypt presets, described in Certificates.

Select the interface you use. The prerequisites and every stage on this page follow that choice.

Prerequisites

  • An Azion account. To create one, refer to Create an account.
  • A workload that lists your domain in its domains. To add a domain, refer to Add a custom domain to a workload.
  • A certificate in PEM format that covers your domain, with its private key, also in PEM and without a passphrase. RSA 2048 keys and P-256 keys are accepted.
  • The Azion CLI, installed and authorized.
  • The certificate and the private key saved as files, such as server.pem and server.key.
  • The ID of your workload.
  • A personal token and curl. To create a token, refer to Personal tokens.
  • The ID of your workload.

Upload the certificate

A server certificate holds the certificate and its private key. Once saved, the private key cannot be read back from the Console or the API. You can upload the certificate alone or with its intermediate certificates.

To upload the certificate with the Azion CLI, pass the paths of the two PEM files:

Shell
01azion create digital-certificate --name my-certificate \
02 --certificate server.pem --private-key server.key

The command prints the ID of the new certificate:

Created Digital Certificate with ID <certificate-id>

Record the ID to bind the certificate to your workload. List the certificates of your account:

azion list digital-certificate --details

The output shows your certificate with the type edge_certificate and the status inactive:

Text
01ID NAME STATUS ISSUER VALIDITY TYPE MANAGED LAST EDITOR LAST MODIFIED
02<certificate-id> my-certificate inactive 2026-01-31 12:00:00+00:00 edge_certificate false <your-email> 2026-01-01 12:00:00.000000 +0000 UTC

The certificate exists in Certificate Manager, and no workload uses it yet.

To upload the certificate with the API, send a POST request to the certificates endpoint. type set to edge_certificate makes it a server certificate. In the body, certificate and private_key are JSON strings. Write each one as a single continuous string that keeps its -----BEGIN and -----END lines, with every line break written as \n. Replace [TOKEN VALUE] with your personal token:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/tls/certificates \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "my-certificate",
08 "type": "edge_certificate",
09 "certificate": "-----BEGIN CERTIFICATE-----\n<certificate-body>\n-----END CERTIFICATE-----\n",
10 "private_key": "-----BEGIN PRIVATE KEY-----\n<private-key-body>\n-----END PRIVATE KEY-----\n"
11}

The API answers with 201 and returns the new certificate. Record its id to bind the certificate to your workload. The certificate exists in Certificate Manager, and no workload uses it yet.

To upload the certificate in Azion Console:

Open the Certificate Manager page

Access Azion Console > Certificate Manager.

Start a new certificate

Select Create Digital Certificate. The Create Digital Certificate page opens.

Select the Server Certificate preset
Name the certificate

In Name, enter a name for the certificate, such as my-certificate.

Paste the certificate

In Certificate, paste the PEM certificate, including its -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. The help text reads “Intermediate certificates are accepted.”

Paste the private key

In Private Key, paste the PEM private key, including its -----BEGIN and -----END lines.

Select Create

The certificate appears in the Certificate Manager list as a TLS Certificate. It stays inactive until a workload uses it.

Bind the certificate to your workload

A workload uses a server certificate only once its tls.certificate field names it. Before you bind it, check that the certificate covers the domains of the workload. The API accepts a certificate that does not cover them.

To bind the certificate with the Azion CLI, save the JSON below as tls.json. Replace <workload-id> and <certificate-id>:

JSON
01{
02 "id": <workload-id>,
03 "tls": {
04 "certificate": <certificate-id>,
05 "ciphers": 7,
06 "minimum_version": "tls_1_3"
07 }
08}

The file sends the whole tls object. It names your certificate and keeps the defaults of a new workload, cipher suite 7 and TLS 1.3 as the minimum version. If your workload uses other values, send those instead. Send the file:

azion update workload --file tls.json

The command prints the ID of the workload:

Updated Workload with ID <workload-id>

The workload names your certificate in tls.certificate.

To bind the certificate with the API, send a PATCH request to your workload with the tls object. It names your certificate and keeps the defaults of a new workload, cipher suite 7 and TLS 1.3 as the minimum version. If your workload uses other values, send those instead. Replace <workload-id> and <certificate-id>:

Shell
01curl --request PATCH \
02 --url https://api.azion.com/v4/workspace/workloads/<workload-id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "tls": {
08 "certificate": <certificate-id>,
09 "ciphers": 7,
10 "minimum_version": "tls_1_3"
11 }
12}

The API accepts the update, and the workload names your certificate in tls.certificate.

To bind the certificate in Azion Console:

Open the Workloads page

Access Azion Console > Workloads.

Open your workload

Select your workload. The Edit Workload page opens.

Turn on HTTPS support

In Protocol Settings, turn on HTTPS support if it is off. Digital Certificate appears only while it is on.

Select your certificate

In Digital Certificate, select your certificate in the My certificates group.

Select Save

Azion Console shows the message “Your workload has been updated”. The workload names your certificate in tls.certificate.

Confirm the certificate is active

Certificate Manager reports a certificate as active once a workload names it. The status shows that your workload uses the certificate.

To confirm the status with the Azion CLI, list the certificates of your account:

azion list digital-certificate --details

The output shows your certificate with the status active:

Text
01ID NAME STATUS ISSUER VALIDITY TYPE MANAGED ...
02<certificate-id> my-certificate active 2026-01-31 12:00:00+00:00 edge_certificate false ...

Your certificate is active, and your workload uses it.

To confirm the status with the API, send a GET request to your certificate. Replace <certificate-id>:

Shell
01curl --request GET \
02 --url https://api.azion.com/v4/workspace/tls/certificates/<certificate-id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]'

The response returns your certificate. These are some of its fields, with status set to active:

JSON
01{
02 "id": <certificate-id>,
03 "managed": false,
04 "name": "my-certificate",
05 "status": "active",
06 "type": "edge_certificate"
07}

Your certificate is active, and your workload uses it.

To confirm the status in Azion Console:

Open the Certificate Manager page

Access Azion Console > Certificate Manager.

Find your certificate

Find your certificate in the list, and confirm that its status is active. A pending certificate shows a warning icon, and a failed certificate shows an error icon with the reason.

Your certificate is active, and your workload uses it.

Binding a certificate is a change to the workload. The change takes several minutes to reach all of Azion’s distributed infrastructure, with no guaranteed duration. Meanwhile, requests can meet the old configuration or the new one. For more information, refer to Propagation.

Next steps

Request a Let's Encrypt certificateHave Azion request a certificate for your domain from Let's Encrypt and renew it for you.CertificatesEvery certificate type, field, status, and error, with the CSR and CRL objects.mTLSCheck client certificates against a Trusted CA certificate on your workload.Issuance and renewalHow Azion validates, issues, and renews a Let's Encrypt certificate.