# How to define a new origin for your application

import Tabs from '~/components/tabs/Tabs'

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

<Apiv4Rollout />

This guide explains how to configure an origin. An origin, also known as a backend, is the server from which Azion retrieves your content. Origins can include object storage services, cloud servers, or other infrastructure that hosts your application assets or data.

There are separate instructions for API v3 using [legacy Origin](/en/documentation/products/build/applications/domains/) settings and API v4 using the new [Connectors](/en/documentation/products/secure/connectors) 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.
:::

---

<Tabs client:visible>
    <Fragment slot="tab.consoleedgeconnector">Console - Connectors</Fragment>
    <Fragment slot="tab.consoleorigins">Console - Origins</Fragment>
    <Fragment slot="tab.apiv4">API v4</Fragment>
    <Fragment slot="tab.apiv3">API v3</Fragment>

<Fragment slot="panel.consoleedgeconnector">

1. [Access Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Connectors**.
2. Click the **+ Connector** button.
3. In the **General** section, give your connector a unique and descriptive name (`My Object Storage Connector`).
4. In the **Connector Type** section, select **HTTP**.

:::tip
To implement the load balancing algorithm for multiple origins, see the [guide on multiple origins with Load Balancer](/en/documentation/products/guides/build/multiple-origins/).
:::

5. In the **Connection Options** section, locate the **Transport Protocol Policy** field and select **Force HTTPS**.
6. In the **Address Management** section, locate the **Address** field and add `httpbin.org`.
7. Under **Host**, add `customhost.com`.
8. Click the **Save** button.

:::note
If your origin is under a host followed by a path, such as `https://bucket.s3.amazonaws.com/applications/your-app`, you must separate the URL and add the host `bucket.s3.amazonaws.com` into the **Address** field. Then add the path `/applications/your-app` into the **Origin path** field.
:::

To activate the Connector in your application:

1. Access the **Rules Engine** tab.
2. Edit the default rule or add a new request rule.
3. Give your rule a name.
4. Select **Request Phase**.
5. Under the **Criteria** section, select the variable `${uri}`.
6. As a comparison operator, select **is equal**.
7. As an argument, add `/httpbin`.
8. In the **Behaviors** section, select **Set Connector** from the behavior list.
9. Select the new Connector you created.
10. Click the **Save** button.
11. Wait a few minutes for the changes to propagate, then access `xxxxxxxxxx.map.azionedge.net/httpbin`.

</Fragment>

<Fragment slot="panel.consoleorigins">

When you [create an application](/en/documentation/products/start-with-a-template/), a default origin is created and activated automatically. This guide shows you how to create and activate a new origin with different configurations without removing or editing the default origin.

1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Applications**.
2. Click the application for which you want to configure a new origin.
3. Select the **Origins** tab.
4. Click the **+ Origin** button.
5. Give your new origin a name. For example: `httpbin.org`.
6. Under **Type**, keep **Single Origin** selected.

:::tip
To implement load balancing algorithm for multiple origins, see the [guide on multiple origins with Load Balancer](/en/documentation/products/guides/build/multiple-origins/).
:::

7. Under **Protocol Policy**, select **Enforce HTTPS**.
8. Under **Address**, add `httpbin.org`.
9. Under **Host Header**, add `customhost.com`.

:::tip[Choosing the right Host Header value]
The **Host Header** controls which value Azion sends in the `Host` HTTP header when connecting to your origin.

- **Specific domain** (e.g., `customhost.com`): Azion always sends this fixed value to the origin, regardless of the domain the user requested. Use this when your origin serves a single virtualhost or requires a specific hostname to route requests correctly.
- **`${host}` variable**: Azion forwards the `Host` header received from the user's request directly to the origin. Use this when your origin serves multiple virtualhosts from the same address.

**Important**: if your origin enforces Host-based access controls, IP allowlists tied to a specific hostname, or CDN configurations that validate the `Host` header, changing this value may cause the origin to reject requests. Verify your origin's virtualhost configuration before modifying this field.
:::

10. Leave **Origin Path** blank.
11. Click **Save**.

:::note
If your origin is under a host followed by a path, such as `https://bucket.s3.amazonaws.com/applications/your-app`, you must separate the URL and add the host `bucket.s3.amazonaws.com` into the **Address** field and add the path `/applications/your-app` into the **Origin path** field.
:::

The origin is created, but it isn't active yet. You need to create a Rules Engine rule to route requests to it.

1. Navigate to the **Rules Engine** tab.
2. Click the **+ Rule** button.
3. Give your rule a name.
4. Select **Request Phase**.
5. Under the **Criteria** section, select the variable `${uri}`.

:::note
The `${uri}` variable may already be selected by default if you haven't activated **Application Accelerator**. For more information on application modules, see the [Applications documentation](/en/documentation/products/build/applications/#modules).
:::

6. As a comparison operator, select **is equal**.
7. As an argument, add `/httpbin`.
8. In the **Behaviors** section, select **Set Origin** from the behavior list.
9. Select the new origin you created.
10. Click **Save**.
11. Wait a few minutes for the changes to propagate, then access `xxxxxxxxxx.map.azionedge.net/httpbin`.
</Fragment>

<Fragment slot="panel.apiv4">

1. Run the following `POST` request in your terminal. Replace `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/) and `<application_id>` with [your application ID](/en/documentation/products/guides/build/configure-main-settings/):

<Code lang="bash" code={` 
curl --request POST \
  --url https://api.azion.com/v4/edge_connector/connectors \
  --header 'Accept: application/json' \
  --header 'Authorization: Token [TOKEN VALUE]' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "httpbin.org SO HTTPS Host:customhost.com",
    "active": true,
    "type": "http",
    "attributes": {
      "addresses": [
        {
          "active": true,
          "address": "httpbin.org",
          "http_port": 80,
          "https_port": 443
        }
      ],
      "connection_options": {
        "dns_resolution": "preserve",
        "transport_policy": "force_https",
        "http_version_policy": "http1_1",
        "host": "customhost.com",
        "path_prefix": "",
        "following_redirect": false,
        "real_ip_header": "X-Real-IP",
        "real_port_header": "X-Real-PORT"
      },
      "modules": {
        "load_balancer": {
          "enabled": false,
          "config": {
            "method": "round_robin",
            "max_retries": 0,
            "connection_timeout": 60,
            "read_write_timeout": 120
          }
        },
        "origin_shield": {
          "enabled": false,
          "config": null
        }
      }
    }
  }'

`} />

  | Key | Description |
  | --- | --- |
  | `name` | Name of the Connector. |
  | `type` | Connector type. Set to `http` for HTTP/HTTPS origins. For load balancing across multiple addresses, see [Work with multiple origins](/en/documentation/products/guides/build/multiple-origins/). |
  | `addresses` | List of origin address objects. For a single origin, you can only send one object in the array. |
  | `transport_policy` | Connection protocol between edge nodes and the origin. When set to `force_https`, enforces HTTPS regardless of the protocol used by the end user. |
  | `host` | Value sent in the `Host` header to the origin. Use a specific FQDN (e.g., `customhost.com`) for a single virtualhost. Use `${host}` to forward the end user's `Host` header, useful when your origin serves multiple virtualhosts. |

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

<Code lang="json" code={`{

{
  "state": "pending",
  "data": {
    "id": <connector_id>,
    "name": "httpbin.org SO HTTPS Host:customhost.com",
    "last_editor": "your-email@example.com",
    "last_modified": "2025-08-14T18:12:20.161667Z",
    "active": true,
    "product_version": "1.0",
    "type": "http",
    "attributes": {
      "addresses": [
        {
          "active": true,
          "address": "httpbin.org",
          "http_port": 80,
          "https_port": 443,
          "modules": null
        }
      ],
      "connection_options": {
        "dns_resolution": "preserve",
        "transport_policy": "force_https",
        "http_version_policy": "http1_1",
        "host": "customhost.com",
        "path_prefix": "",
        "following_redirect": false,
        "real_ip_header": "X-Real-IP",
        "real_port_header": "X-Real-PORT"
      },
      "modules": {
        "load_balancer": {
          "enabled": false,
          "config": null
        },
        "origin_shield": {
          "enabled": false,
          "config": null
        }
      }
    }
  }
}
`} />


3. Run the following `POST` request in your terminal to bind the new Connector to your application. Replace `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/), `<application_id>` with [your application ID](/en/documentation/products/guides/build/configure-main-settings/), and `<connector_id>` with the Connector ID returned in the previous step:

<Code lang="bash" code={` 
curl --request POST \
  --url https://api.azion.com/v4/edge_application/applications/<application_id>/request_rules \
  --header 'Accept: application/json' \
  --header 'Authorization: Token [TOKEN VALUE]' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "string",
  "active": true,
  "criteria":
    [
      {
        "conditional": "if",
        "variable": "\${uri}",
        "operator": "is_equal",
        "argument": "/httpbin"
      }
    ]
  ],
  "behaviors": [
    {
      "type": "set_edge_connector",
      "attributes": {
        "value": "<connector_id>"
      }
    }
  ]
}'
`} />

4. A successful response confirms the rule was created.
5. Wait a few minutes for the changes to propagate, then access `xxxxxxxxxx.map.azionedge.net/httpbin`. Try accessing any other unconfigured URI — you should receive a `404` error.

</Fragment>

<Fragment slot="panel.apiv3">

1. Run the following `POST` request in your terminal. Replace `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/) and `<application_id>` with [your application ID](/en/documentation/products/guides/build/configure-main-settings/):

<Code lang="bash" code={`
curl --location 'https://api.azionapi.net/edge_applications/<application_id>/origins' \
--header 'Accept: application/json; version=3' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token [TOKEN VALUE]' \
--data '{
        "name": "httpbin.org SO HTTPS Host:customhost.com",
        "origin_type": "single_origin",
        "addresses": [
            {
                "address": "httpbin.org"
            }
        ],
        "origin_protocol_policy": "https",
        "host_header": "customhost.com"
}'
`} />

  | Key | Description |
  | --- | --- |
  | `name` | Name of the origin. |
  | `origin_type` | Origin type. Set to `single_origin` for a single address. For load balancing across multiple addresses, see [Work with multiple origins](/en/documentation/products/guides/build/multiple-origins/). |
  | `addresses` | List of origin address objects. For `single_origin`, you can only send one object in the array. |
  | `origin_protocol_policy` | Connection protocol between edge nodes and the origin. When set to `https`, enforces HTTPS regardless of the protocol used by the end user. |
  | `host_header` | Value sent in the `Host` header to the origin. Use a specific FQDN (e.g., `customhost.com`) for a single virtualhost. Use `${host}` to forward the end user's `Host` header, useful when your origin serves multiple virtualhosts. |

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

<Code lang="json" code={`{
    "results": {
        "origin_id": <origin_id>,
        "origin_key": <origin_key>,
        "name": "httpbin.org SO HTTPS Host:customhost.com",
        "origin_type": "single_origin",
        "addresses": [
            {
                "address": "httpbin.org",
                "weight": null,
                "server_role": "primary",
                "is_active": true
            }
        ],
        "origin_protocol_policy": "https",
        "is_origin_redirection_enabled": false,
        "host_header": "customhost.com",
        "method": "",
        "origin_path": "",
        "connection_timeout": 60,
        "timeout_between_bytes": 120,
        "hmac_authentication": false,
        "hmac_region_name": "",
        "hmac_access_key": "",
        "hmac_secret_key": ""
    }
}
`} />

:::caution
Endpoints that require origin identification use the `origin_key` value, not the `origin_id`. For example, a `PATCH` request must target `https://api.azionapi.net/edge_applications/<application_id>/origins/<origin_key>`. The exception is when referencing an origin outside the `/origins/` endpoints — such as when creating a Rules Engine rule — where `origin_id` is used instead.
:::

3. Run the following `POST` request in your terminal. Replace `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/), `<application_id>` with [your application ID](/en/documentation/products/guides/build/configure-main-settings/), and `<origin_id>` with the origin ID returned in the previous step:

<Code lang="bash" code={`
curl --location 'https://api.azionapi.net/edge_applications/<application_id>/rules_engine/request/rules' \
--header 'Accept: application/json; version=3' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token [TOKEN VALUE]' \
--data '{
    "name": "Set httpbin /httpbin",
    "behaviors": [
        {
            "name": "set_origin",
            "target": "<origin_id>"
        }
    ],
    "criteria": [
        [
            {
                "variable": "\${uri}",
                "operator": "is_equal",
                "conditional": "if",
                "input_value": "/httpbin"
            }
        ]
    ]
}'
`} />

4. A successful response confirms the rule was created.
5. Wait a few minutes for the changes to propagate, then access `xxxxxxxxxx.map.azionedge.net/httpbin`. Try accessing any other unconfigured URI — you should receive a `404` error.

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

</Tabs>


:::note[Host Header behavior]
The **Host Header** field controls which value Azion sends in the `Host` header when forwarding requests to your origin.

- **`${host}`**: passes the `Host` header received from the end user directly to the origin. Use this when your origin serves multiple virtualhosts from the same address and needs to distinguish between them.
- **A specific domain name** (for example, `customhost.com`): sends a fixed value regardless of what the user requested. Use this when your origin responds to a virtualhost at an address different from the one configured in DNS, or when you need to enforce a specific hostname for origin-side routing, SSL certificate matching, or access control.

Leaving the field blank causes Azion to use the value set in the **Address** field as the default Host header.
:::

:::caution[Origin configuration restrictions]
Keep the following constraints in mind when configuring an origin:

- The **Address** field must be a valid FQDN or IPv4/IPv6 address. Do not include the protocol (`http://` or `https://`) in this field; use the **Origin Protocol Policy** setting instead.
- If your origin content lives under a subpath (for example, `bucket.s3.amazonaws.com/apps/my-app`), place the hostname in **Address** and the path in **Origin Path**. Combining both in the **Address** field will cause request failures.
- Changing the origin address or Host Header of an active origin affects all rules that reference it. Review your Rules Engine configuration before making changes in production.
- For origins that require HMAC authentication (such as private object storage buckets), you must provide valid **Region**, **Access Key**, and **Secret Key** credentials. Incorrect or missing credentials will result in `403` errors from the origin.
:::