Skip to content

[EDU-6450] AI documentation update - 2025-04-11 - work with origins #1599

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
PedroMiolaSilva wants to merge 4 commits into
base: main
Choose a base branch
from
Open

[EDU-6450] AI documentation update - 2025-04-11 - work with origins #1599

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f36fdce
(feat): add guide for defining a new origin in Azion applications
PedroMiolaSilva Apr 11, 2025
d3bd3dd
docs(origins): resolve TODOs and improve narrative clarity
GabrielAzion Jul 11, 2026
9569c8d
Merge branch 'main' into EDU-6450-azion-copilot-support-tickets-work-…
GabrielAzion Jul 11, 2026
9040ad5
docs(origins): refine instructions for clarity and consistency
GabrielAzion Jul 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 54 additions & 35 deletions src/content/docs/en/pages/build-journey/edit-edge-app/edit-origins/origins.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ In this guide, there are separate instructions for API v3 and API v4. If you're
<Fragment slot="panel.consoleedgeconnector">

1. [Access Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Connectors**.
2. Click the **+ + Connector** button.
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**.

Expand All @@ -55,35 +55,35 @@ 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 a name for your 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 and access `xxxxxxxxxx.map.azionedge.net/httpbin`.
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 will show you how to create and activate a new origin with different configurations without removing or editing the default origin.
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 the option **Single Origin** selected.
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`
8. Under **Address**, add `httpbin.org`.
9. Under **Host Header**, add `customhost.com`.

:::tip[Choosing the right Host Header value]
Expand All @@ -95,36 +95,36 @@ The **Host Header** controls which value Azion sends in the `Host` HTTP header w
**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 **Path** blank.
11. Click the **Save** button.
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.
:::

You've created a new origin, but it isn't active in your application yet. You need to define what will trigger a request to the new origin.
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 a name for your rule.
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 didn't activate **Application Accelerator**. For more information on Applications modules, see the [Applications documentation](/en/documentation/products/build/applications/#modules).
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 the **Save** button.
11. Wait a few minutes for the changes to propagate and access `xxxxxxxxxx.map.azionedge.net/httpbin`.
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, replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/) and the `<application_id>` variable with [your application ID](/en/documentation/products/guides/build/configure-main-settings/):
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 \
Expand Down Expand Up @@ -177,11 +177,11 @@ curl --request POST \

| Key | Description |
| --- | --- |
| `name` | Sets the string in value as a name of the origin. |
| `type` | Sets the new Connector type to `http`. For more information on load balancing, check [Work with multiple origins](/en/documentation/products/guides/build/multiple-origins/). |
| `addresses` | Takes a list of objects for each address of the origin. Since this is an entry of the single origin type, you may only send one object with the `address` value in the array. |
| `transport_policy` | When `https`, enforces an HTTPS connection with the origin, not affecting the protocol from user requests. |
| `host` | Sets the value of the `Host` header sent to the origin. Use a specific FQDN (e.g., `customhost.com`) when your origin serves a single virtualhost. Use `${host}` to forward the `Host` header received from the user's request, which is useful when your origin serves multiple virtualhosts. If your origin enforces Host-based access controls, ensure this value matches what the origin expects. |
| `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:

Expand Down Expand Up @@ -233,7 +233,7 @@ curl --request POST \
`} />


3. Run the following `POST` request in your terminal to bind the new Connector to your Applications replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/), the `<application_id>` variable with [your application ID](/en/documentation/products/guides/build/configure-main-settings/), and the `<connector_id>` variable with the Connector ID from the previous step:
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 \
Expand Down Expand Up @@ -265,14 +265,14 @@ curl --request POST \
}'
`} />

3. You'll receive a response confirming that the rule was created.
4. Wait a few minutes for the changes to propagate and access `xxxxxxxxxx.map.azionedge.net/httpbin`. Also, try accessing any other unconfigured URI and you should receive a `404` error.
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, replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/) and the `<application_id>` variable with [your application ID](/en/documentation/products/guides/build/configure-main-settings/):
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' \
Expand All @@ -294,11 +294,11 @@ curl --location 'https://api.azionapi.net/edge_applications/<application_id>/ori

| Key | Description |
| --- | --- |
| `name` | Sets the string in value as a name of the origin. |
| `origin_type` | Sets the new origin type to `single_origin`. For more information on load balancing, check [Work with multiple origins](/en/documentation/products/guides/build/multiple-origins/). |
| `addresses` | Takes a list of objects for each address of the origin. Since this is an entry of the single origin type, you may only send one object with the `address` value in the array. |
| `origin_protocol_policy` | When `https`, enforces an HTTPS connection with the origin, not affecting the protocol from user requests. |
| `host_header` | Sets the value of the `Host` header sent to the origin. Use a specific FQDN (e.g., `customhost.com`) when your origin serves a single virtualhost. Use `${host}` to forward the `Host` header received from the user's request, which is useful when your origin serves multiple virtualhosts. If your origin enforces Host-based access controls, ensure this value matches what the origin expects. |
| `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:

Expand Down Expand Up @@ -331,11 +331,11 @@ curl --location 'https://api.azionapi.net/edge_applications/<application_id>/ori
}
`} />

:::caution[warning]
Endpoints that require origin identification use the `origin_key` value. For example, a `PATCH` request for an origin must be made to the URL `https://api.azionapi.net/edge_applications/<application_id>/origins/<origin_key>`. This doesn't apply to cases when you must reference an origin outside the `/origins/` endpoints, such as when creating a new rule to activate your origin.
:::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, replacing `[TOKEN VALUE]` with your [personal token](/en/documentation/products/guides/personal-tokens/), the `<application_id>` variable with [your application ID](/en/documentation/products/guides/build/configure-main-settings/), and the `<origin_id>` variable with the origin ID from when you [created a new origin via API](#via-api):
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' \
Expand Down Expand Up @@ -363,12 +363,31 @@ curl --location 'https://api.azionapi.net/edge_applications/<application_id>/rul
}'
`} />

4. You'll receive a response confirming that the rule was created.
5. Wait a few minutes for the changes to propagate and access `xxxxxxxxxx.map.azionedge.net/httpbin`. Also, try accessing any other unconfigured URI: you should receive a `404` error.
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>
</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.
:::