# How to create a digital certificate

import Tabs from '~/components/tabs/Tabs'
import Code from '~/components/Code/Code.astro'

import Apiv4Rollout from '~/includes/snippets/apiv4Rollout/en/snippet.mdx'

<Apiv4Rollout />

If your application runs on HTTPS, you'll need to register a certificate with Azion [Certificate Manager](/en/documentation/products/secure/firewall/certificate-manager/). A TLS digital certificate confirms a website's identity and protects data transfers. It secures financial transactions and any exchange of sensitive information, from login credentials to personal data.

You can also request that a **Let's Encrypt certificate** be generated for your domain through Azion. The process for requesting a Let's Encrypt certificate is different from custom certificates. See [how to generate a Let's Encrypt certificate](/en/documentation/products/guides/how-to-generate-a-lets-encrypt-certificate/) for more information.

:::note
- Azion now offers the flexibility of issuing and renewing Let’s Encrypt certificates via API using either the DNS-01 or HTTP-01 challenge, allowing you to choose the method that best suits your needs.
- Don't have a digital certificate? Check the guide on [How to acquire and register a Digital Certificate with Azion](/en/documentation/products/guides/secure/digital-certificates/).
:::

There are separate instructions for the [legacy Domains](/en/documentation/products/build/applications/domains/) settings and the new [Workloads](/en/documentation/products/secure/workloads) product.

:::tip
In this guide, there are separate instructions for API v3 and API v4. If you're not sure which steps apply to your account, see [the Verify Your Account Migration guide](/en/documentation/products/guides/verify-account-migration/) to determine if your account has already been migrated.
:::

---

## Option 1: Upload custom certificate

<Tabs client:visible>
    <Fragment slot="tab.console">Console</Fragment>
    <Fragment slot="tab.api">API</Fragment>

<Fragment slot="panel.console">
1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Certificate Manager**.
2. Click the **+ Digital Certificate** button.
3. Name your certificate.
4. Select the **Import a server certificate** option.
5. In the field **Certificate**, paste the certificate.
6. In the **Private Key** field, paste the private key.
7. Click the **Save** button.
</Fragment>

<Fragment slot="panel.api">
1. Acquire the X.509 certificate from a CA.
2. Replace any line breaks with `\n`, including for the begin and end markers, to turn the certificate into a string.
3. Do the same to the private key.
4. Run the following cURL command in your terminal, replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/) and adding your certificate and private key to the fields:

<Code lang="bash" code={`
curl --request POST \
  --url https://api.azion.com/v4/digital_certificates/certificates \
  --header 'Accept: application/json' \
  --header 'Authorization: Token [TOKEN VALUE]' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "CERT yourdomain.com",
  "certificate": "-----BEGIN CERTIFICATE-----\n<your_private_key>\n-----END CERTIFICATE-----",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n<your_private_key>\n-----END RSA PRIVATE KEY-----",
  "type": "edge_certificate",
  "active": true
}'
`} />

  | Key | Description |
  | --- | --- |
  | `name` | Sets the string in the value as a name of the certificate entry with Azion. |
  | `certificate` | Takes your certificate as a value. Must be a continuous string. |
  | `private_key` | Takes your private key as a value. Must be a continuous string. |

Upon uploading your custom certificate, you'll receive a successful response:

<Code lang="json" code={`
{
    "results": {
        "id": <digital_certificate_id>,
        "name": "CERT yourdomain.com",
        "issuer": "",
        "subject_name": [],
        "validity": "2028-03-24 20:09:00-03:00",
        "status": "Active",
        "certificate_type": "edge_certificate",
        "managed": false
    }
}
`} />
</Fragment>

</Tabs>

---

## Option 2: Upload Trusted CA for mTLS

<Tabs client:visible>
    <Fragment slot="tab.console">Console</Fragment>
    <Fragment slot="tab.api">API</Fragment>

<Fragment slot="panel.console">

1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Certificate Manager**.
2. Click the **+ Digital Certificate** button.
3. Name your certificate.
4. Select the **Import a Trusted CA certificate** option.
5. In the field **Certificate**, paste the certificate.
6. Click the **Save** button.
</Fragment>

<Fragment slot="panel.api">

1. Acquire a trusted certificate signed by your CA.
2. Replace any line breaks with `\n`, including for the begin and end markers, to turn the certificate into a string.
3. Run the following cURL command in your terminal, replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/) and adding your certificate and to the fields:

<Code lang="bash" code={`
curl --request POST \
  --url https://api.azion.com/v4/digital_certificates/certificates \
  --header 'Accept: application/json' \
  --header 'Authorization: Token [TOKEN VALUE]' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "TCA yourdomain.com",
  "certificate": "-----BEGIN CERTIFICATE-----\n<your_private_key>\n-----END CERTIFICATE-----",
  "type": "trusted_ca_certificate",
  "active": true
}'
`} />

  | Key | Description |
  | --- | --- |
  | `name` | Sets the string in the value as a name of the certificate entry with Azion. |
  | `certificate` | Takes your certificate as a value. Must be a continuous string. |
  | `certificate_type` | When set to `trusted_ca_certificate`, the endpoint no longer requires a private key entry. |

Upon uploading your Trusted CA, you'll receive a successful response:

<Code lang="json" code={`
{
    "results": {
        "id": <digital_certificate_id>,
        "name": "TCA yourdomain.com",
        "issuer": "",
        "subject_name": [],
        "validity": "2028-03-24 20:09:00-03:00",
        "status": "Active",
        "certificate_type": "trusted_ca_certificate",
        "managed": false
    }
}
`} />
</Fragment>

</Tabs>

---

## Associate certificate to domain

Now you need to associate your certificate to an Azion domain:

<Tabs client:visible>
    <Fragment slot="tab.consoleworkloads">Console - Workloads</Fragment>
    <Fragment slot="tab.consoledomain">Console - Domains</Fragment>
    <Fragment slot="tab.apiv4">API v4</Fragment>
    <Fragment slot="tab.apiv3">API v3</Fragment>

<Fragment slot="panel.consoleworkloads">

1. On the upper-left corner of the page, open the **Products menu**, represented by three horizontal lines > **Workloads**.
2. Select the desired Workload.
3. In **Certificate Manager**, select the certificate you created in the previous steps.
4. Make sure the domain listed in the **Subdomain** and **Domain** fields are the same as the issued certificate for your domain.
5. Click the **Save** button.
6. Wait a couple of minutes for the changes to propagate. 

You can access your HTTPS application and check the security settings using your browser or run the following OpenSSL command, replacing `yourdomain.com` with one of the CNAMEs of the domain:

<Code lang="bash" code={`
openssl s_client -showcerts -connect yourdomain.com:443
`} />
</Fragment>

<Fragment slot="panel.consoledomain">

1. On the upper-left corner of the page, open the **Products menu**, represented by three horizontal lines > **Domains**.
2. Select the desired domain.
3. In **Digital Certificate**, select the certificate you created in the previous steps.
4. Make sure the CNAMEs listed in the **CNAME** field are the same as the issued certificate for your custom domain.
5. Click the **Save** button.
6. Wait a couple of minutes for the changes to propagate. 

You can access your HTTPS application and check the security settings using your browser or run the following OpenSSL command, replacing `yourdomain.com` with one of the CNAMEs of the domain:

<Code lang="bash" code={`
openssl s_client -showcerts -connect yourdomain.com:443
`} />
</Fragment>

<Fragment slot="panel.v4">

1. Run the following `GET` request to retrieve your Workload's id:

<Code lang="bash" code={`
curl --request GET \
  --url https://api.azion.com/v4/workspace/workloads \
  --header 'Accept: application/json' \
  --header 'Authorization: Token [TOKEN VALUE]'
`} />

2. You'll receive a response similar to this:

<Code lang="json" code={`
  "results": [
    {
      "id": <workload_id>,
      "name": "My Workload",
      "active": true,
      "last_editor": "your-email@example.com",
      "last_modified": "2025-08-06T17:53:47.460211Z",
      "infrastructure": 1,
      "tls": {
        "certificate": null,
        "ciphers": 7,
        "minimum_version": "tls_1_3"
    },
    }
   ]
`} />

3. Locate the domain you wish to associate to the certificate and copy the `workload_id` value received in the response.
4. Run a `PATCH` request, adding the `workload_id` as a path, to update the `digital_certificate_id` field with the id you received in the creation process:

:::note[Optional]
As shown in the example below, if you didn't update the Domain and Subdomain fields with your custom domain yet, make sure to add the host and any common names for the application that are protected by the certificate. This will be useful when you later [point your domain](/en/documentation/products/guides/point-domain-to-azion/) or [migrate your NS resolution](/en/documentation/products/guides/migrate-ns-to-azion/) to Azion.
:::

<Code lang="bash" code={`
curl --request PATCH \
  --url https://api.azion.com/v4/workspace/workloads/{workload_id} \
  --header 'Accept: application/json' \
  --header 'Authorization: Token [TOKEN VALUE]' \
  --header 'Content-Type: application/json' \
  --data '{
    "tls": {
      "certificate": <digital_certificate_id>
    },
    "domains": [
      "yourdomain.com"
    ]
  }'
`} />

5. You should receive a response with the updated data.
6. Wait a couple of minutes for the changes to propagate. Then, access your HTTPS application and check the security settings using your browser or run the following OpenSSL command, replacing `yourdomain.com` with one of the CNAMEs of the domain:

<Code lang="bash" code={`
openssl s_client -showcerts -connect yourdomain.com:443
`} /> 

:::tip
Check the [Azion API documentation](https://api.azion.com/v3) to know more about all features available via API.
:::
</Fragment>

<Fragment slot="panel.apiv3">

1. Run the following `GET` request to retrieve your domain's id:

<Code lang="bash" code={`
curl --location 'https://api.azionapi.net/domains' \
--header 'Accept: application/json; version=3' \
--header 'Authorization: Token [TOKEN VALUE]' \
`} />

2. You'll receive a response similar to this:

<Code lang="json" code={`
{
    ...
    "results": [
        {
            "id": <domain_id>,
            "name": "My Domain",
            "cnames": [],
            "cname_access_only": true,
            "digital_certificate_id": null,
            "edge_application_id": <edge_application_id>,
            "is_active": true,
            "domain_name": "xxxxxxxxxx.map.azionedge.net"
        }
    ]
}
`} />

3. Locate the domain you wish to associate to the certificate and copy the `domain_id` value received in the response.
4. Run a `PATCH` request, adding the `domain_id` as a path, to update the `digital_certificate_id` field with the id you received in the creation process:

:::note[Optional]
As shown in the example below, if you didn't update the CNAME field with your custom domain yet, make sure to add the host and any common names for the application that are protected by the certificate. This will be useful when you later [point your domain](/en/documentation/products/guides/point-domain-to-azion/) or [migrate your NS resolution](/en/documentation/products/guides/migrate-ns-to-azion/) to Azion.
:::

<Code lang="bash" code={`
curl --location --request PATCH 'https://api.azionapi.net/domains/<domain_id>' \
--header 'Accept: application/json; version=3' \
--header 'Authorization: Token [TOKEN VALUE]' \
--header 'Content-Type: application/json' \
--data '{
    "digital_certificate_id": <digital_certificate_id>,
    "cnames": [
        "yourdomain.com"
    ]
}'
`} />

5. You should receive a response with the updated data.
6. Wait a couple of minutes for the changes to propagate. Then, access your HTTPS application and check the security settings using your browser or run the following OpenSSL command, replacing `yourdomain.com` with one of the CNAMEs of the domain:

<Code lang="bash" code={`
openssl s_client -showcerts -connect yourdomain.com:443
`} /> 

:::tip
Check the [Azion API documentation](https://api.azion.com/v3) to know more about all features available via API.
:::
</Fragment>

</Tabs>