GetCnameToken

GetCnameToken retrieves an existing CNAME token. Use the wildcard parameter to specify whether to retrieve the token for an exact CNAME or for a wildcard CNAME.

Usage notes

For an Agentic Bucket, the wildcard parameter is required: wildcard=true retrieves the token for a wildcard CNAME, and wildcard=false retrieves the token for an exact CNAME. For a standard bucket, if you omit this parameter, the value defaults to false.
To retrieve the token for a wildcard CNAME, set cname to the base domain name without the *. prefix, such as example.com.

Request syntax

GET /?cname&comp=token&cname=example.com&wildcard=true HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: GMT Date
Authorization: SignatureValue

Request headers

This operation uses only common request headers. For more information, see Common HTTP headers.

Request parameters

Parameter

Type

Required

Example

Description

cname

String

Yes

example.com

The target domain name. For an exact CNAME, set this parameter to the complete domain name, such as console.example.com. For a wildcard CNAME, set this parameter to the base domain name without the *. prefix, such as example.com.

wildcard

String

Standard bucket: No

Agentic Bucket: Yes

true

Specifies whether to retrieve the token for a wildcard CNAME. Valid values:

true: retrieves the token for a wildcard CNAME.
false: retrieves the token for an exact CNAME.

For an Agentic Bucket, this parameter is required. Set it explicitly to true or false. For a standard bucket, if you omit this parameter, the value defaults to false.

Response headers

This operation returns only common response headers. For more information, see Common HTTP headers.

Response elements

Element	Type	Example	Description
CnameToken	Container	N/A	The container that stores the CNAME token. Parent nodes: none Child nodes: Bucket, Cname, Token, and ExpireTime
Bucket	String	examplebucket	The name of the bucket to which the CNAME is mapped. Parent nodes: CnameToken Child nodes: none
Cname	String	example.com	The name of the CNAME that is mapped. Parent nodes: CnameToken Child nodes: none
Token	String	be1d49d863dea9ffeff3df7d6455****	The CNAME token returned by OSS. Parent nodes: CnameToken Child nodes: none
ExpireTime	String	Wed, 23 Feb 2022 21:16:37 GMT	The time when the CNAME token expires. Parent nodes: CnameToken Child nodes: none

Examples

Sample requests

Query the CNAME token for an exact CNAME of a standard bucket

GET /?cname&comp=token&cname=example.com HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 17 Apr 2025 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Query the CNAME token for a wildcard CNAME of an Agentic Bucket

GET /?cname&comp=token&cname=example.com&wildcard=true HTTP/1.1
Host: myab-$uid-$region-ab-apsr.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 17 Apr 2025 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample responses

The CNAME token is retrieved.

HTTP/1.1 200 OK
x-oss-request-id: 5C1B138A109F4E405B2D
Date: Mon, 26 Jul 2021 13:08:38 GMT
Content-Length: 118
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<CnameToken>
  <Bucket>myab-$uid-$region-ab-apsr</Bucket>
  <Cname>example.com</Cname>
  <Token>be1d49d863dea9ffeff3df7d6455****</Token>
  <ExpireTime>Fri, 01 Aug 2026 03:00:00 GMT</ExpireTime>
</CnameToken>

The CNAME token is not created or has expired.

HTTP/1.1 404 Not Found
x-oss-request-id: 5C1B138A109F4E405B2D
Date: Mon, 26 Jul 2021 13:08:38 GMT
Content-Length: 118
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchCnameToken</Code>
  <Message>The specified cname token does not exist.</Message>
  <RequestId>6215FE05DA0E27393F005F0E</RequestId>
  <HostId>myab-$uid-$region-ab-apsr.oss-cn-hangzhou.aliyuncs.com</HostId>
  <Bucket>myab-$uid-$region-ab-apsr</Bucket>
  <Cname>example.com</Cname>
</Error>

OSS SDKs

The following OSS SDKs support the GetCnameToken operation:

ossutil

For information about the ossutil command that corresponds to the GetCnameToken operation, see get-cname-token.

Error codes

Error code	HTTP status code	Description
InvalidArgument	400	The following are possible causes of the error: You did not specify the CNAME to query, or the CNAME format is invalid. The Domain element contains invalid characters, such as the wildcard literal `*.example.com`. The `wildcard` parameter is not specified for an Agentic Bucket, or the `wildcard` value is invalid.
NoSuchCnameToken	404	No token has been created for this CNAME, or the token has expired.
MethodNotAllowed	405	The CNAME feature is not enabled for the target bucket type.