All Products
Search

This Product

    API Gateway:Bind a custom domain name to an API group

    Document Center

    API Gateway:Bind a custom domain name to an API group

    Last Updated:Jun 08, 2026

    Bind your domain name to an API Gateway group so that clients can call APIs through your domain name instead of the default second-level domain.

    Overview

    Domain names, API groups, and APIs

    • Bind your domain name to an API group to create a mapping between them.

    • API Gateway routes each incoming HTTP request to the correct API group and API based on the domain name, HTTP method, and path.

    Important

    API Gateway assigns a default public second-level domain name to each API group, but daily API calls through this domain are limited: 1,000 per day in Chinese mainland regions and 100 per day in other regions. Responses also include a "Content-Disposition: attachment; filename=ApiResponseForInnerDomain" header. To remove these limits, bind a custom domain name to the API group.

    ICP filing for a domain name

    To bind a domain name to an API group in a Chinese mainland region, you must obtain an ICP number or add Alibaba Cloud as a service provider in your ICP filing. No ICP filing is required outside the Chinese mainland.

    Note

    ICP filing is not required for internal domain names.

    Domain name ownership verification

    A domain name can be bound to an API group only if it is not already bound to another group on the same instance with the same base path, and does not conflict with existing wildcard domain names. Verify domain ownership by using one of the following methods:

    1. Add a CNAME record that maps your domain name to the system-assigned second-level domain name.

    2. Add a TXT record. Use the format "API group ID.Domain name" for the hostname and "apigateway-domain-verification=Public second-level domain name" for the record value.

      For example, if the API group ID is b7eb2f79e64f4431b08bbb948ed2567e, the public second-level domain name is b7eb2f79e64f4431b08bbb948ed2567e-cn-hangzhou.alicloudapi.com, and the bound domain is youdomain.com or *.yourdomain, add a TXT record with hostname (RR) b7eb2f79e64f4431b08bbb948ed2567e.yourdomain.com and record value apigateway-domain-verfication=b7eb2f79e64f4431b08bbb948ed2567e-cn-hangzhou.alicloudapi.com.

    Important

    • Internal domain names do not require ownership verification.

    • If you bind a domain name without adding a CNAME record, client requests to that domain cannot reach API Gateway.

    • To bind the same domain name to multiple API groups:

      • Same instance: the API groups must have different base paths (up to 300 bytes each).

      • Different instances: clients must specify the target instance in their DNS settings.

    Procedure

    Bind a public or internal domain name by following 1. Bind a single domain name or 2. Bind a wildcard domain name. The main steps are:

    1. Domain name resolution: Add a CNAME or TXT record to map your domain name to the second-level domain name of the API group. Domain name resolution.

      • Public domain name resolution: Map your public domain name to the public second-level domain name of the API group. Public domain name resolution.

      • Internal domain name resolution: Map your internal domain name to the internal second-level domain name of the API group. Internal domain name resolution.

    2. Domain name binding: Bind your domain name to the API group on the Group Details page. Domain name binding.

    3. Optional. If multiple HTTPS domain names are bound to the API group, configure a default domain name. Configure the default domain name of the API group.

    1. Bind a single domain name

    Domain name resolution

    Public domain name resolution

    1. Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups and select a region.

    2. On the API Groups page, click the target API group. In the Basic Information section, find the public second-level domain name.

    3. Log on to the DNS console. Choose Public DNS > Authoritative DNS Resolution. Click the Authoritative Domain Names tab, and then click the domain name to open the DNS Settings tab.

    4. On the DNS Settings tab, click Add DNS Record. Set Record Type to CNAME, Hostname to the domain name prefix, and Record Value to the public second-level domain name. Click OK.

    Internal domain name resolution

    1. Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups and select a region.

    2. On the API Groups page, click the target API group. In the Basic Information section, find the internal VPC domain name.

    3. Log on to the DNS console. Click Private DNS (PrivateZone). In the upper-right corner of the Private DNS (PrivateZone) page, click Configuration Mode. On the User Defined Zones tab, click Add New Zone.

    4. In the Add Built-in Authoritative Zone panel, specify Built-in Authoritative Zone and Alibaba Cloud VPC, and click OK.

      For Domain Type, select Built-in Authoritative Acceleration Zone. This is recommended for the lowest resolution latency.

      Note

      For Built-in Authoritative Zone, enter the custom (internal) domain name bound to the API group. This domain name is used only for private DNS (PrivateZone) in VPCs.

    5. Click the zone name to open the Resource Records Settings tab. Click Add Record. In the Add Record panel, set Record Type to CNAME, Hostname to the domain name prefix, and Record Value to the internal VPC domain name. Click OK.

    Note

    • On ECS instances in the associated VPC, the private zone record overrides the public DNS record. The internal domain name resolves based on the private zone record.

    • The public DNS record is not affected in a VPC. Adding a private zone record prevents empty authoritative zones from overwriting the public DNS record, which would cause resolution errors. Activate Alibaba Cloud DNS PrivateZone.

    Domain name binding

    1. Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups and select a region.

    2. On the API Groups page, click the target API group to open the Group Details page. In the Independent Domains section, click Bind Domain Name.

    3. In the Bind Domain Name dialog box, set the following parameters and click Confirm.

      Parameter

      Description

      Domain Name

      The domain name to bind to the API group.

      Environment

      The environment for the domain name. Valid values:

      • Test: Calls only test environment APIs.

      • Pre: Calls only staging environment APIs.

      • Production: Calls only production environment APIs.

      • Default (X-Ca-Stage): Calls APIs in any environment. Add the X-Ca-Stage header to specify the target environment.

      Network Type

      Internet: API calls over the Internet only. Internal Network: API calls over internal networks only.

    Note

    • Internal domain names do not require ownership verification. However, binding fails if the domain name conflicts with one bound to another API group on the same instance.

    • The network type cannot be changed after binding. To correct it, delete the domain name and rebind it.

    FAQ about domain name binding

    Why does domain name binding fail?

    • The domain name is already bound to another API group on the same instance, or a wildcard domain name conflicts with a single domain name. Unbind the conflicting domain name first.

    • The domain name is bound to an API group owned by a different user, or a wildcard domain name conflict exists. Complete Domain name ownership verification before binding.

    Verify API calls

    After binding, use the domain name to call APIs. Example curl request:

    curl http://yourdomain.com/apipath -i
HTTP/1.1 200 OK
Date: Mon, 23 Mar 2020 08:40:01 GMT
Connection: keep-alive
Keep-Alive: timeout=25
Server: Jetty(7.2.2.v20101205)
X-Ca-Request-Id: E2B8CBAB-D6EF-4576-838F-44DDC1A6B20D
    Important

    If an internal domain name is bound, call APIs from within the associated VPC.

    2. Bind a wildcard domain name

    You can bind wildcard domain names to API groups. Resolve the wildcard domain name to the public second-level domain name and bind it in the API Gateway console. After binding, use the wildcard domain name to call APIs in the group.

    Bind a wildcard domain name

    The process is similar to 1. Bind a single domain name. For example, to route all subdomains of abc.com (such as 1.abc.com and 2.abc.com) to API Gateway:

    1. In the DNS console, create a CNAME record mapping *.abc.com to the public second-level domain name.

    2. On the Group Details page in the API Gateway console, bind *.abc.com to the API group.

    Note

    Only VPC-based instances support wildcard domain names. After binding, clients can call APIs through any subdomain such as 1.abc.com or 2.abc.com. For example, an API that supports anonymous GET calls can also be accessed through any *.abc.com subdomain.

    Usage notes

    1. Verify ownership of the wildcard domain name before binding. Domain name ownership verification.

    2. After binding, configure a wildcard domain name template on the Group Details page to enable API calls through the wildcard domain.

    Click Edit Wildcard Domain Name Template in the Actions column. Enter one or more matching templates such as {groupId}.api.foo.com or {userId}.user.api.foo.com, separated by Enter, comma, or semicolon. Click OK.

    Note

    Variable fields in the template are passed as parameters to backend services.

    Configure the default domain name of an API group

    You can upload HTTPS certificates for your domain names. If multiple HTTPS domain names are bound to a single API group, set one as the default. When a client that does not support SNI initiates an SSL handshake, API Gateway returns the default domain certificate; otherwise, a random certificate is returned. This feature is available only for dedicated instances. Shared instances do not support default certificates, which may cause certificate errors for non-SNI clients.

    Important

    On a dedicated instance, if multiple API groups have default domain names configured, only the first API group's default domain name is loaded.