# How to configure a domain

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

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

<Apiv4Rollout />

With Azion, you can create and run applications directly at the edge. To allow access to your application through the browser and start receiving users and monitoring metrics, you need to configure a domain.

To create a free domain address for your application in the format `xxxxxxxxxx.map.azionedge.net`, follow the steps in the appropriate tab below. 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.
:::

---

## Configuring a domain with Azion

<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">

To create a Workload:

1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Workloads**.
2. Click the **+ Workload** button.
3. Give your Workload a name.
4. Select the **Infrastructure** for your Workload: **Production Infrastructure** or **Staging Infrastructure** (test environment).
5. Define your application hostnames in the **Subdomain** and **Domain** fields. You can use [custom domain](#linking-a-custom-domain-to-your-application) addresses to link to your application.
6. In **Applications**, select your Applications.
7. In **Firewall**, select your Firewall.
8. In **Digital Certificate**, select, create a new, or use the Azion SAN certificate if you're aiming to use the Azion Custom Domain or the Workload Domain.
9. Click the **Save** button.

Wait a few minutes for your new Workload to propagate and access your `xxxxxxxxxx.map.azionedge.net` address to see your Application online.

</Fragment>

<Fragment slot="panel.consoledomain">

1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Domains**.
2. Click the **+ Domain** button.
3. Give your domain a name.
4. Select the **Environment Type** for your domain: **Global Edge Network** (production environment) or **Staging Network** (test environment).
5. In **Applications**, select your application.
6. In **Firewall**, select your firewall.
7. Disable the **CNAME access only switch**. This'll enable users to access your application using the `xxxxxxxxxx.map.azionedge.net` address.
8. In the **CNAME** field, you may list [custom domain](#linking-a-custom-domain-to-your-application) addresses to link to your application.
9. In **Digital Certificate**, select the **Azion SAN** certificate.
10. Click the **Save** button.

Wait a few minutes for your new domain to propagate to the edge nodes and access your `xxxxxxxxxx.map.azionedge.net` address to see your application online.
</Fragment>
<Fragment slot="panel.apiv4">
1. Run the following `POST` request in your terminal, replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/) to create a new Workload.

<Code lang="bash" code={`curl --request POST \
  --url https://api.azion.com/v4/workspace/workloads \
  --header 'Accept: application/json' \
  --header 'Authorization: Token [TOKEN VALUE]' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example CN0 DC0",
  "active": true,
  "infrastructure": 1,
  "protocols": {
    "http": {
      "versions": [
        "http1",
        "http2"
      ]
    }
  },
  "workload_domain_allow_access": true
  }
}`}/>


| Key | Description |
| --- | --- |
| `name` | Sets the value as the name of the domain entry with Azion. You may modify this value to fit your needs, since it does not represent a domain address. |
| `workload_domain_allow_access` | When set to `true`, enables access via the `xxxxxxxxxx.map.azionedge.net` Azion address. |
| `infrastructure` | Infrastructure for your Workload: **Production Infrastructure** (1) or **Staging Infrastructure** (2) |
| `digital_certificate_id` | When `null`, selects the **Azion SAN** certificate. You can also [associate a digital certificate](/en/documentation/products/guides/create-a-digital-certificate/#via-api) to your Workload. |

2. You'll receive a response similar to:

<Code lang="json" code={`{
  "state": "pending",
  "data": {
    "id": <workload_id>,
    "name": "Example CN0 DC0",
    "active": true,
    "last_editor": "your-email@example.com",
    "last_modified": "2025-07-25T18:58:25.817955Z",
    "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": [],
    "workload_domain_allow_access": true,
    "workload_domain": "xxxxxxxxxxx.azionedge.net",
    "product_version": "1.0"
  }
}`}/>

3. Copy the URL in the `workload_domain` value and paste it in a text editing app to access later. 

4. Now you must bind the created **Workload** to an **Application**. This is done by creating a Workload Deployment. Run the following `POST` request in your terminal, replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/), `<edge_application_id>` with the ID of the desired Application and `<workload_id>` with the ID of the Workload you created on the previous step.

<Code lang="bash" code={`curl --request POST \
  --url https://api.azion.com/v4/workspace/workloads/<workload_id>/deployments \
  --header 'Accept: application/json' \
  --header 'Authorization: Token [TOKEN VALUE]' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Workload Deployment",
    "current": true,
    "active": true,
    "strategy": {
      "type": "default",
      "attributes": {
        "edge_application": <edge_application_id>
      }
    }
  }'
}`}/>

5. The  `workload_domain` received in the response carries your application's Azion domain address as a string. Wait a few minutes for the changes to propagate and paste its value without the double quotes (`"`) in your browser to access your application.

:::tip
Check the [Azion API documentation](https://api.azion.com/v4#) to know more about all features available via API.
:::
</Fragment>
<Fragment slot="panel.apiv3">
1. Run the following `POST` request in your terminal, replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/), the `<edge_application_id>` variable with the [ID of your application](/en/documentation/products/guides/build/configure-main-settings/):

<Code lang="bash" code={`curl --location 'https://api.azionapi.net/domains' \
--header 'Accept: application/json; version=3' \
--header 'Authorization: Token [TOKEN VALUE]'\
--header 'Content-Type: application/json' \
--data '{
    "name": "Example CN0 DC0",
    "cname_access_only": false,
    "digital_certificate_id": null,
    "edge_application_id": <edge_application_id>
}'`}/>

  | Key | Description |
  | --- | --- |
  | `name` | Sets the string in value as a name of the domain entry with Azion. You may modify this value to fit your needs, since it does not represent a domain address. |
  | `cname_access_only` | When set to `false`, enables access via the Azion address. |
  | `digital_certificate_id` | When `null`, selects the **Azion SAN** certificate. You can also [associate a digital certificate](/en/documentation/products/guides/create-a-digital-certificate/#via-api) to your domain. |
  | `edge_application_id` | The [ID of the application](/en/documentation/products/guides/build/build-an-application/#via-api) linked to the domain. |

2. You'll receive a response similar to:

```json
{
    "results": {
        "id": <domain_id>,
        "name": "Example CN0 DC0",
        "cnames": [],
        "cname_access_only": false,
        "digital_certificate_id": null,
        "edge_application_id": <edge_application_id>,
        "is_active": true,
        "domain_name": "xxxxxxxxxx.map.azionedge.net",
        "is_mtls_enabled": false,
        "mtls_verification": "enforce",
        "mtls_trusted_ca_certificate_id": null
    }
}
```

3. The `domain_name` received in the response carries your application's Azion domain address as a string. Wait a few minutes for the changes to propagate and paste its value without the double quotes (`"`) in your browser to access your application.

:::tip
Check the [Azion API documentation](https://api.azion.com/) and the [OpenAPI specification](https://github.com/aziontech/azionapi-openapi/) to know more about all features available via API.
:::
</Fragment>

</Tabs>

---

## Linking a custom domain to your application

In addition to the default Azion domain, you have the option to associate a **custom domain** in CNAME format, such as `yourdomain.com`, with your application. This allows you to customize the domain name that users will use to access your application.

When a user enters the custom domain name in their browser, a DNS lookup process takes place. During the DNS lookup, the user's browser sends a request to a DNS server to find the IP address associated with the custom domain. The DNS server checks its database to find the corresponding IP address for the custom domain name. If the custom domain is configured to point to the Azion domain, the DNS server returns the IP address of the nearest edge node in the Azion network.

Once the user's browser receives the IP address, it establishes a connection with the appropriate edge node. The edge node then serves the requested content, and the user's browser displays the application.

You can choose to customize your domain by [associating a domain record](/en/documentation/products/guides/point-domain-to-azion/) or [migrating your name resolution to Azion](/en/documentation/products/guides/migrate-ns-to-azion/).