# How to point a domain to Azion

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

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

<Apiv4Rollout />

If you already own a domain, you can associate your domain CNAME entries to your Azion Workload address effectively directing access to your application. 

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.

Before you point your traffic to Azion, you can test your custom domain on the edge locally by [staging your application through the hosts file](/en/documentation/products/guides/stage-applications-through-hosts-file/).

:::note
This process will require you to associate a CNAME record to your domain. To associate an ANAME record to your application, [migrate your nameservers to Azion](/en/documentation/products/guides/migrate-ns-to-azion/).
:::

:::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.
:::

---

## Step 1: Verifying custom domain

To point your Azion domain to a custom domain, you need to list the CNAMEs you want to configure for the application:

<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. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Workloads**.
2. Click the workload you want to associate your custom domain to.
3. In the **Subdomain** and **Domain** fields, add the custom domains for the application. For example: `yourdomain.com`.
4. Disable the the **Workload Domain Allow Access** switch.
5. Click the **Save** button.

Now your Azion Workload is ready to be [associated to a custom domain on your DNS provider](#step-2-modifying-domain-records).
</Fragment>

<Fragment slot="panel.consoledomain">

1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Domains**.
2. Click the domain you want to associate your custom domain to.
3. In the **CNAME** field, add the custom domains for the application. For example: `yourdomain.com`.
4. Enable the **CNAME Access Only** switch.
5. Click the **Save** button.

Now your Azion domain is ready to be [associated to a custom domain on your DNS provider](#step-2-modifying-domain-records).
</Fragment>

<Fragment slot="panel.apiv4">

1. Run the following `GET` request to retrieve your workload's ID, replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/):

<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={`
{
  "count": 3,
  "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"
      },
      "protocols": {
        "http": {
          "versions": [
            "http1",
            "http2"
          ],
          "http_ports": [
            80
          ],
          "https_ports": [
            443
          ],
          "quic_ports": null
        }
      },
      "mtls": {
        "verification": null,
        "certificate": null,
        "crl": null
      },
      "domains": [
        "xxxxxxx.azion.app"
      ],
      "workload_domain_allow_access": false,
      "workload_domain": "xxxxxxxx.map.azionedge.net",
      "product_version": "1.0"
    }
`} />


3. Locate the workload you wish to link to the custom domain and copy the `workload_id` value received in the response.
4. Run a `PATCH` request, , replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/) and adding the `workload_id` as a path, to update the `domains` field with the domains you wish to configure:

<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 '{
    "domains": [
      "yourdomain.com",
      "*.yourdomain.com"
    ]
  }'
`} />

  | Key | Description |
  | --- | --- |
  | `domains` | Accepts a list of CNAMEs values for the workload. For example, `["*.yourdomain.com", "*.yourdomain.org"]`. |

:::tip
If your application uses HTTPS, you might want to combine this process with the [association of a digital certificate](/en/documentation/products/guides/create-a-digital-certificate/) to your custom domain.
:::

5. You should receive a response with the updated data.

</Fragment>


<Fragment slot="panel.apiv3">

1. Run the following `GET` request to retrieve your domain's ID, replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/):

<Code lang="bash" code={`
curl --location 'https://api.azionapi.net/domains?order_by=name&sort=asc&page=1&page_size=10' \
--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": "yourdomain.com CA1 DC-yourdomain.com",
            "cnames": [],
            "cname_access_only": true,
            "digital_certificate_id": <digital_certificate_id>,
            "edge_application_id": <edge_application_id>,
            "is_active": true,
            "domain_name": "xxxxxxxxxx.map.azionedge.net"
        }
    ]
}
`} />

3. Locate the domain you wish to link to the custom domain and copy the `domain_id` value received in the response.
4. Run a `PATCH` request, , replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/) and adding the `domain_id` as a path, to update the `cnames` field with the domains you wish to configure:

<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 '{
    "cnames": [
        "yourdomain.com",
        "*.yourdomain.com"
    ]
}'
`} />

  | Key | Description |
  | --- | --- |
  | `cnames` | Accepts a list of CNAMEs for the domains as values. For example, `["*.yourdomain.com", "*.yourdomain.org"]`. |

:::tip
If your application uses HTTPS, you might want to combine this process with the [association of a digital certificate](/en/documentation/products/guides/create-a-digital-certificate/) to your custom domain.
:::

5. You should receive a response with the updated data.
</Fragment>

</Tabs>

---

## Step 2: Modifying domain records

Once you have a domain, you need to access your DNS provider and locate the **records management** area. There, you can modify every entry associated with your domain. The entry you need to associate your Azion domain to is a **CNAME** record.

:::note
Some services don't allow you to change your ANAME resolution directly. You can point your custom ANAME record to your application by [migrating your nameservers to Azion](/en/documentation/products/guides/migrate-ns-to-azion/).
:::

At your DNS provider, you can add or modify a `www` CNAME record and associate it to your application. See the documentation on how to edit domain records of some of the most popular DNS providers below:

- [AWS Route53](https://aws.amazon.com/pt/getting-started/hands-on/get-a-domain/)
- [GoDaddy](https://www.godaddy.com/help/manage-dns-records-680)
- [Namecheap](https://www.namecheap.com/support/knowledgebase/article.aspx/767/10/how-to-change-dns-for-a-domain/)

To configure your DNS records:

1. Sign in to your DNS provider.
2. Choose your domain.
3. Locate the page where you can modify DNS records for your domain.
4. Create or edit the `www` CNAME record of your domain by filling out the information:

| Name | Value | Type |
| --- | --- | --- |
| `www` | `xxxxxxxxxx.map.azionedge.net` | CNAME |

:::tip
Some providers allow you to add a wildcard (`*`) subdomain instead of a specific subdomain to cover all scenarios. This way, you won't need to specify that `www.yourdomain.com` and `blog.yourdomain.com` point to the same application address.
:::

5. Don't forget to save your settings.

Note that there might be a delay in propagation time when you access your application. If that's the case, [you can run the dig command](/en/documentation/products/guides/run-the-dig-command/) in your terminal to check the DNS records of your edge node. For example:

<Code lang="bash" code={`
dig +short yourdomain.org @200.0.0.0
`} />

Once the changes have propagated, you'll be able to access your application through your custom domain.

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