DocsICP FilingConsole
Documentation
Home Page Object Storage Service Developer Reference API reference Bucket-level operations CNAME CreateCnameToken

CreateCnameToken - Create a CNAME token to verify domain name ownership

Updated at:
Copy as MD
Product
My Favorites

CreateCnameToken creates the CNAME token required to verify domain name ownership. Use the wildcard parameter to specify whether to create the token for an exact CNAME or for a wildcard CNAME.

Usage notes

  • By default, a CNAME token expires 72 hours after it is created. If you call this operation again while a token is still valid, OSS returns the existing token.

  • For an Agentic Bucket, the wildcard parameter is required: wildcard=true creates a token for a wildcard CNAME, and wildcard=false creates a token for an exact CNAME.

  • For a standard bucket, creating a token for an exact CNAME works exactly as it does for the existing OSS CNAME operations. No new parameters are required.

Request syntax

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

<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

Request headers

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

Request parameters

Parameter

Type

Required

Example

Description

wildcard

String

Standard bucket: No

Agentic Bucket: Yes

true

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

  • true: creates a token for a wildcard CNAME.

  • false: creates a 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.

The wildcard parameter takes different values for each bucket type:

Bucket type

Parameter omitted

wildcard=false

wildcard=true

Standard bucket

Allowed. Creates a token for an exact CNAME.

Allowed. Creates a token for an exact CNAME.

Not allowed

Agentic Bucket

Not allowed

Allowed. Creates a token for an exact CNAME.

Allowed. Creates a token for a wildcard CNAME.

Note

A single token for a (bucket, CNAME) pair covers both the exact and the wildcard scope.

Request elements

Element

Type

Required

Example

Description

BucketCnameConfiguration

Container

Yes

N/A

The container that stores the CNAME configuration.

Parent nodes: none

Child nodes: Cname

Cname

Container

Yes

N/A

The container that stores the CNAME information.

Parent nodes: BucketCnameConfiguration

Child nodes: Domain

Domain

String

Yes

example.com

The custom domain name. To create a token for an exact CNAME, set this element to the complete domain name, such as console.example.com. To create a token for a wildcard CNAME, set this element to the base domain name without the *. prefix, such as example.com.

Parent nodes: Cname

Child nodes: none

Idempotency

The idempotency of CreateCnameToken depends on the bucket type and on whether the CNAME is already mapped to the current bucket:

  • Standard bucket: If the CNAME is already mapped to the current bucket in any state other than deleted, OSS returns NoNeedCreateCnameToken and you do not need to create a token.

  • Agentic Bucket: OSS returns NoNeedCreateCnameToken only if the current Agentic Bucket has already mapped the base domain name to a CNAME of the same type.

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

    • Create a CNAME token for a standard bucket

      POST /?cname&comp=token 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

<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

    • Create a CNAME token for a wildcard CNAME of an Agentic Bucket

      POST /?cname&comp=token&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

<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

    • Create a CNAME token for an exact CNAME of an Agentic Bucket

      POST /?cname&comp=token&wildcard=false 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

<BucketCnameConfiguration>
  <Cname>
    <Domain>console.example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

  • Sample responses

    • The CNAME token is created.

      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 number of CNAME tokens exceeds the upper limit.

      HTTP/1.1 400 Bad Request
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>TooManyCnameToken</Code>
  <Message>You have attempted to create more cname token than allowed.</Message>
  <RequestId>6215FD21DA0E27393F004E9E</RequestId>
  <HostId>127.0.0.1</HostId>
  <Bucket>examplebucket</Bucket>
</Error>

OSS SDKs

The following OSS SDKs support the CreateCnameToken operation:

ossutil

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

Error codes

Error code

HTTP status code

Description

InvalidArgument

400

The following are possible causes of the error:

  • The Domain element contains invalid characters, such as the wildcard literal *.example.com.

TooManyCnameToken

400

The number of tokens created for the same bucket exceeds the upper limit.

NoNeedCreateCnameToken

200

The CNAME is already mapped to the current bucket, and you do not need to create a token. For a standard bucket, OSS returns this response when the CNAME is already mapped to the current bucket in any state other than deleted. For an Agentic Bucket, OSS returns this response only if the base domain name is already mapped to the current Agentic Bucket by a CNAME of the same type.

MethodNotAllowed

405

The CNAME feature is not enabled for the target bucket type.

Previous：CNAMENext：GetCnameToken