Access OSS via endpoints and bucket domains - Object Storage Service

OSS assigns each bucket a set of access domain names, allowing you to flexibly access OSS resources based on different business requirements and network environments. This topic describes the format, applicable scenarios, and configuration methods of each domain name type to help you choose the appropriate access method.

Core concepts

A standard OSS access address consists of multiple hierarchical components. Understanding the following four core concepts correctly is essential for accessing OSS properly:

Concept	Description	Format	Purpose
Region ID	General region identifier	`<region-id>`, for example `ap-southeast-1`	Used for scenarios such as V4 signatures in SDKs and ossutil
Dedicated Region ID	OSS dedicated region identifier	`oss-<region-id>`	Used for scenarios such as composing Endpoints, API request parameters, and response parameters
Endpoint	Service access address	`oss-<region-id>.aliyuncs.com`	Configured in SDKs and ossutil to establish a network connection with the OSS service
Bucket domain name	Access address of a specific bucket	`<bucket-name>.oss-<region-id>.aliyuncs.com`	Used for scenarios such as direct browser access, generating signed URLs, hosting static websites, and custom domain CNAME resolution

These four concepts form a hierarchy: Region ID identifies a geographic location, for which OSS assigns a corresponding Dedicated Region ID. The Dedicated Region ID combines with the domain name suffix to form the Endpoint (service access address). To access a specific bucket, you use the Bucket domain name (resource access address) formed by combining the bucket name with the Endpoint.

Note

For the Region IDs of each region, see Regions and endpoints.

Prerequisites

Before you access OSS through an API or SDK, you must obtain an AccessKey for identity authentication. An AccessKey consists of an AccessKey ID and an AccessKey secret.

To obtain an AccessKey:

Log on to the AccessKey management page of the Resource Access Management (RAM) console.
Click Create AccessKey to create a new AccessKey, or enable a disabled AccessKey.
Select the I acknowledge the security risks of using an Alibaba Cloud account AccessKey check box, and then click Continue using the Alibaba Cloud account AccessKey.

For more information, see Create an AccessKey pair.

Domain name types

OSS provides different types of access domain names based on network environments and performance requirements.

Important

Due to a policy change to improve compliance and security, starting March 20, 2025, new OSS users must use a custom domain name (CNAME) to perform data API operations on OSS buckets located in Chinese mainland regions. Default public endpoints are restricted for these operations. Refer to the official announcement for a complete list of the affected operations. If you access your data via HTTPS, you must bind a valid SSL Certificate to your custom domain. This is mandatory for OSS Console access, as the console enforces HTTPS.

Domain name type	Applicable scenarios	Domain name format	Billing characteristics	Activation required
Public endpoint	Public network access from web applications, mobile clients, and so on	Endpoint: `oss-<region-id>.aliyuncs.com` Bucket domain name: `<bucket-name>.oss-<region-id>.aliyuncs.com`	Billed by public network traffic	Available by default
Internal endpoint	Internal network access within the same Alibaba Cloud region (for example, from ECS)	Endpoint: `oss-<region-id>-internal.aliyuncs.com` Bucket domain name: `<bucket-name>.oss-<region-id>-internal.aliyuncs.com`	No traffic fees	Available by default
Transfer acceleration domain name	High-speed cross-region and cross-border upload/download	Endpoint: `oss-accelerate.aliyuncs.com` Bucket domain name: `<bucket-name>.oss-accelerate.aliyuncs.com`	Billed by transfer acceleration	You must enable the transfer acceleration feature
CNAME domain name	Custom domain name binding (such as static resource hosting)	Bucket domain name: `<bucket-name>.<region-id>.<cname-domain>`	Billed by public network traffic	You must access OSS through a custom domain name
Dual-stack domain name	Accessing OSS in IPv6 network environments	Endpoint: `<region-id>.oss.aliyuncs.com` Bucket domain name: `<bucket-name>.<region-id>.oss.aliyuncs.com`	Public network access is billed by public network traffic; internal network access incurs no traffic fees	Supported in some regions

Public endpoint

Designed for internet access, this is suitable for scenarios such as web applications, mobile clients, and cross-region access. SDKs use the public endpoint by default. You only need to specify the Region ID to complete the configuration, without specifying the Endpoint explicitly.

Internal endpoint

Designed for the Alibaba Cloud internal network, this is suitable for scenarios such as ECS instances accessing OSS within the same region. Internal access avoids public network traffic fees while providing more stable network connections and lower latency. Recommendations for use:

DNS configuration optimization
When using an internal endpoint, we strongly recommend that you configure Alibaba Cloud private DNS addresses (100.100.2.136 and 100.100.2.138) to ensure that the correct VIP address is obtained and to avoid OSS access exceptions caused by DNS resolution issues.
Completeness of VIP network segment routing configuration
OSS assigns a fixed address range for the internal VIP network segment of each region, and the system dynamically switches IP addresses within the specified VIP network segment. When on-premises devices and data centers access OSS through the internal network, the routing configuration must cover the complete VIP network segment; otherwise, incomplete network routing may cause connection interruptions. For the internal VIP network segment information of each region, see Regions and endpoints.
Important
Ensure that your routing configuration covers the complete VIP network segment to avoid network connectivity issues caused by incomplete configuration. If OSS service availability is affected due to missing VIP network segment configuration, the resulting losses shall be borne by the configuring party.
When you access OSS across regions through VPC peering connections or Cloud Enterprise Network (CEN), add the VIP network segment of the OSS internal endpoint in the peer region to the VPC route table. The VIP network segment is fixed, and the routing configuration remains valid for the long term without connectivity failures caused by segment changes.
Security group rule configuration
When using an ECS instance to access OSS through the internal network, the security group rules must not block access to any VIP network segment, to ensure network connectivity.

How do I generate a publicly accessible URL for a file uploaded through an internal endpoint?

A file stored in OSS can be accessed through any endpoint, regardless of whether it was uploaded through an internal endpoint or a public endpoint. The endpoint used for the upload does not affect how the file is accessed. If you uploaded a file through an internal endpoint, you only need to replace the domain name with the public endpoint of the corresponding region when you generate the access URL.

For example, if you uploaded the file example.jpg through the internal endpoint oss-cn-hangzhou-internal.aliyuncs.com, the internal access URL is:

https://bucket.oss-cn-hangzhou-internal.aliyuncs.com/example.jpg

To generate a publicly accessible URL, replace the internal endpoint with the public endpoint:

https://bucket.oss-cn-hangzhou.aliyuncs.com/example.jpg

Transfer acceleration domain name

A dedicated domain name that becomes available after you enable the transfer acceleration feature. It optimizes the data transmission path through global acceleration nodes and is suitable for high-speed cross-region and cross-border upload/download scenarios, significantly improving the network quality of long-distance access.

CNAME domain name

A dedicated resolution domain name that OSS generates for a bucket, used for custom domain name binding scenarios. When you need to access OSS through a custom domain name, you should point the CNAME record of the custom domain name to this domain name instead of the public endpoint.

OSS assigns a CNAME domain name within the region for each bucket, and different buckets may be assigned different domain names. Compared with all buckets sharing the same public endpoint, CNAME domain names distribute access links, providing higher availability. Notes for use:

Used only for DNS resolution: The CNAME domain name is used only for the DNS resolution configuration of a custom domain name and does not support direct access.
Access through a custom domain name: After completing custom domain name binding and CNAME resolution configuration, access OSS resources through the custom domain name.

Dual-stack domain name

An Endpoint that supports both IPv4 and IPv6 dual-stack access, allowing clients in IPv6 network environments to directly connect to OSS resources. When using a dual-stack domain name, clients require no special configuration; in a pure IPv6 or dual-stack network environment, DNS automatically resolves and preferentially uses IPv6 addresses to establish connections. For the dual-stack domain name information of each region, see Regions and endpoints.

How to verify IPv6 support of a dual-stack domain name?

Use the dig AAAA command to verify whether a dual-stack Endpoint supports IPv6 access. Take the Singapore region as an example:

dig AAAA ap-southeast-1.oss.aliyuncs.com

If IPv6 is supported, the ANSWER SECTION in the command output displays an AAAA record:

ap-southeast-1.oss.aliyuncs.com. 60 IN  AAAA    240b:4000:f10::2c5

Usage examples

Browser

Important

When you access files such as HTML and images through the access domain names provided by OSS, the browser forces a download instead of an online preview. To enable file preview, access OSS through a custom domain name.

The following example demonstrates how to obtain the signed URL of a file in a private bucket through the console. For more ways to obtain signed URLs, see Use presigned URLs to download or preview files.

Go to the Bucket list and click the target bucket.
Click the file name of the target file or View Details in the Actions column, set Domain Name to Public Endpoint, and then click Copy Object URL.
Access the URL in a browser.

ossutil

The following example demonstrates how to use the ossutil command-line tool to download a file. ossutil uses the public endpoint by default, and you can specify other types of Endpoints through the -e parameter:

ossutil cp oss://<bucket-name>/<object-name> <local-path> -e <endpoint>

Parameter configurations for different domain name types:

Domain name type	Parameter configuration
Public endpoint (default)	You can omit the `-e` parameter, or specify `-e oss-<region-id>.aliyuncs.com`
Internal endpoint	`-e oss-<region-id>-internal.aliyuncs.com`
Transfer acceleration domain name	`-e oss-accelerate.aliyuncs.com`
Custom domain name	`-e <custom-domain> --addressing-style cname`

SDK

The following shows initialization examples of the V2 SDKs for common languages. SDKs use the public endpoint by default, and you only need to specify the Region to complete the configuration.

Java

OSSClient client = OSSClient.newBuilder()
        .credentialsProvider(provider)
        .region("<region-id>")
        .build();

For the complete initialization code, see OSS Java SDK V2.

Python

cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
cfg.region = '<region-id>'

client = oss.Client(cfg)

For the complete initialization code, see OSS Python SDK V2.

Go

cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("<region-id>")

client := oss.NewClient(cfg)

For the complete initialization code, see OSS Go SDK V2.

PHP

$cfg = Configuration::loadDefault();
$cfg->setCredentialsProvider($provider);
$cfg->setRegion('<region-id>');

$client = new Oss\Client($cfg);

For the complete initialization code, see OSS PHP SDK V2.

C#

var cfg = OSS.Configuration.LoadDefault();
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
cfg.Region = "<region-id>";

using var client = new OSS.Client(cfg);

For the complete initialization code, see OSS C# SDK V2.

Node.js

const client = new OSS({
    region: 'oss-<region-id>',
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
});

For the complete initialization code, see OSS Node.js SDK.

Switch the domain name type

The V2 SDKs support quickly switching the domain name type through configuration items, without manually concatenating the Endpoint string:

Language	Public endpoint	Internal endpoint	Transfer acceleration domain name	Dual-stack domain name
Java	Set only `region`	`.useInternalEndpoint(true)`	`.useAccelerateEndpoint(true)`	`.useDualStackEndpoint(true)`
Python	Set only `region`	`use_internal_endpoint = True`	`use_accelerate_endpoint = True`	`use_dualstack_endpoint = True`
Go	Set only `Region`	`WithUseInternalEndpoint(true)`	`WithUseAccelerateEndpoint(true)`	`WithUseDualStackEndpoint(true)`
PHP	Set only `setRegion`	`setUseInternalEndpoint(true)`	`setUseAccelerateEndpoint(true)`	`setUseDualStackEndpoint(true)`
C#	Set only `Region`	`UseInternalEndpoint = true`	`UseAccelerateEndpoint = true`	`UseDualStackEndpoint = true`