Configure the Host header

How the Host header works

The Host header tells API Gateway which backend application or site to route a request to when multiple apps share the same server IP. A common case:

• The backend service is of the virtual private cloud (VPC) type, and multiple applications or sites run in the associated VPC. The Host header identifies which one to forward the request to.

When to configure the Host header: Only when your backend uses virtual-host-based routing (multiple apps behind one IP). If your backend is a dedicated server, the default behavior is usually sufficient — API Gateway sets the Host header to your configured backend address.

API Gateway offers five configuration methods. When multiple methods are active, the following priority order determines which one takes effect:

Configure the Host header

Choose the method that fits your backend setup and follow the corresponding steps.

Method 1: Enable Pass Host Header for the API group

This option forwards the client's original Host header to the backend, instead of using the backend address you configured.

Default behavior (Pass Host Header off):

Host: backend.test.com   ← API Gateway uses your configured backend address

With Pass Host Header on:

Host: apigateway.test.com   ← API Gateway forwards the client's original Host header

To enable it:

1. Log on to the API Gateway console.

2. In the left-side navigation pane, choose API Management > API Groups.

3. Click the name of your target API group.

4. Find the Pass Host Header switch and turn it on.

Method 2: Add the host constant parameter to the API definition

When creating an API, add a constant parameter named host. Set Parameter Location to Head and enter the backend domain name as the parameter value.

Method 3: Configure the Host parameter for VPC access authorization

1. Log on to the API Gateway console.

2. In the left-side navigation pane, choose API Management > VPC Access Authorizations.

3. In the upper-right corner, click Create Authorization.

4. Select the region where the VPC is located, then click Create Authorization.

5. In the Create VPC Access Authorization dialog box, configure the following parameters:

   • Region

   • VPC Authorization Name: 4 to 50 characters

   • VPC ID

   • Instance ID or Address: supports ECS or SLB instance IDs, private IPs, or internal ALB domain names

   • Port

   • Host: enter the target Host header value

6. Click OK.

Method 4: Configure a host for the backend service

1. Log on to the API Gateway console.

2. In the left-side navigation pane, choose Manage APIs > Backend Services.

3. In the upper-right corner, click Create Backend Service and create a backend service of the HTTP/HTTPS or VPC type. Only these two types support host configurations.

4. After the backend service is created, find it in the list and click Configure Backend Service and View Associated APIs in the Actions column.

5. On the Backend Service Definition page, click the tab for your target environment (for example, Test).

6. Click Create in the upper-right corner, then define the backend service URL and the Host field.

The Host field sets the Host header that API Gateway sends when forwarding requests to this backend service.

Method 5: Configure the Host header in a backend routing plug-in

Use the httpTargetHostName or vpcTargetHostName parameter in a backend routing plug-in to set the Host header. This method has the highest priority and overrides all other configurations.

For parameter details and configuration syntax, see section 1.3 of Backend routing plug-ins.

Priority of Host header configurations

If you configure the Host header by using multiple methods, the configurations take effect based on the following priority order: backend routing plug-in > backend service configuration > VPC access authorization > API group configuration > API definition.