API
  • History
  • Introduction
  • API Category
  • Making API Requests
    • Request Structure
    • Common Params
    • Signature v3
    • Signature
    • Responses
  • Site APIs
    • CreateZone
    • DescribeIdentifications
    • ModifyZone
    • DeleteZone
    • ModifyZoneStatus
    • CheckCnameStatus
    • IdentifyZone
    • DescribeZones
    • VerifyOwnership
  • Acceleration Domain Management APIs
    • CreateAccelerationDomain
    • DescribeAccelerationDomains
    • ModifyAccelerationDomain
    • ModifyAccelerationDomainStatuses
    • DeleteAccelerationDomains
    • CreateSharedCNAME
    • BindSharedCNAME
    • DeleteSharedCNAME
  • Site Acceleration Configuration APIs
    • CreateRule
    • DeleteRules
    • DescribeHostsSetting
    • DescribeRules
    • DescribeRulesSetting
    • DescribeZoneSetting
    • ModifyRule
    • ModifyZoneSetting
  • Alias Domain APIs
    • CreateAliasDomain
    • DescribeAliasDomains
    • ModifyAliasDomain
    • ModifyAliasDomainStatus
    • DeleteAliasDomain
  • Security Configuration APIs
    • CreateSecurityIPGroup
    • DescribeSecurityIPGroup
    • ModifySecurityIPGroup
    • DeleteSecurityIPGroup
    • DescribeOriginProtection
    • DescribeSecurityTemplateBindings
    • ModifySecurityPolicy
    • BindSecurityTemplateToEntity
    • DescribeSecurityIPGroupInfo
  • Layer 4 Application Proxy APIs
    • CreateL4Proxy
    • ModifyL4Proxy
    • ModifyL4ProxyStatus
    • DescribeL4Proxy
    • DeleteL4Proxy
    • CreateL4ProxyRules
    • ModifyL4ProxyRules
    • ModifyL4ProxyRulesStatus
    • DescribeL4ProxyRules
    • DeleteL4ProxyRules
    • CreateApplicationProxy
    • ModifyApplicationProxy
    • ModifyApplicationProxyStatus
    • DescribeApplicationProxies
    • DeleteApplicationProxy
    • CreateApplicationProxyRule
    • ModifyApplicationProxyRule
    • ModifyApplicationProxyRuleStatus
    • DeleteApplicationProxyRule
  • Content Management APIs
    • CreatePurgeTask
    • DescribePurgeTasks
    • CreatePrefetchTask
    • DescribePrefetchTasks
    • DescribeContentQuota
  • Data Analysis APIs
    • DescribeDDoSAttackData
    • DescribeDDoSAttackEvent
    • DescribeDDoSAttackTopData
    • DescribeOverviewL7Data
    • DescribeTimingL4Data
    • DescribeTimingL7AnalysisData
    • DescribeTopL7AnalysisData
    • DescribeTimingL7CacheData
    • DescribeTopL7CacheData
  • Log Service APIs
    • DownloadL7Logs
    • DownloadL4Logs
    • CreateCLSIndex
    • CreateRealtimeLogDeliveryTask
    • ModifyRealtimeLogDeliveryTask
    • DeleteRealtimeLogDeliveryTask
    • DescribeRealtimeLogDeliveryTasks
  • Billing APIs
    • CreatePlan
    • UpgradePlan
    • RenewPlan
    • ModifyPlan
    • IncreasePlanQuota
    • DestroyPlan
    • CreatePlanForZone
    • BindZoneToPlan
    • DescribeBillingData
    • DescribeAvailablePlans
  • Certificate APIs
    • DescribeDefaultCertificates
    • ModifyHostsCertificate
  • Load Balancing APIs
    • CreateOriginGroup
    • ModifyOriginGroup
    • DeleteOriginGroup
    • DescribeOriginGroup
  • Custom Response Page APIs
    • CreateCustomizeErrorPage
    • DescribeCustomErrorPages
    • ModifyCustomErrorPage
    • DeleteCustomErrorPage
  • Diagnostic Tool APIs
    • DescribeIPRegion
  • Version Management APIs
    • CreateConfigGroupVersion
    • DeployConfigGroupVersion
    • DescribeConfigGroupVersionDetail
    • DescribeConfigGroupVersions
    • DescribeDeployHistory
    • DescribeEnvironments
  • Data Types
  • Error Codes
이 페이지는 현재 영어로만 제공되며 한국어 버전은 곧 제공될 예정입니다. 기다려 주셔서 감사드립니다.

ModifyHostsCertificate

1. API Description

Domain name for API request: teo.intl.tencentcloudapi.com.

This API is used to configure the certificate of a site. You can use your own certificate or apply for a free certificate.
To use an external certificate, upload the certificate to SSL Certificates Console first, and then input the certificate ID in this API. For details, see Deploying Own Certificates to EdgeOne Domains.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter NameRequiredTypeDescription
ActionYesStringCommon Params. The value used for this API: ModifyHostsCertificate.
VersionYesStringCommon Params. The value used for this API: 2022-09-01.
RegionNoStringCommon Params. This parameter is not required.
ZoneIdYesStringID of the site.
Hosts.NYesArray of StringDomain names that you need to modify the certificate configuration
ModeNoStringCertificate configuration mode. Values:
  • disable: (Default) Do not configure the certificate
  • eofreecert: Use a free certificate provided by EdgeOne
  • sslcert: Configure an SSL certificate.
  • ServerCertInfo.NNoArray of ServerCertInfoSSL certificate configuration. This parameter is effective only when the mode is sslcert. You only need to provide the CertId of the corresponding certificate. You can check the CertId from the SSL Certificate List.
    ClientCertInfoNoMutualTLSIn the mutual authentication scenario, this field represents the client's CA certificate, which is deployed inside the EO node and used for the client to authenticate the EO node. By default, it is disabled. If it is left blank, it indicates retaining the original configuration.

    3. Output Parameters

    Parameter NameTypeDescription
    RequestIdStringThe unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

    4. Example

    Example1 Configuring an SSL Certificate

    This example shows you how to configure an SSL certificate (CertId is J2JqATrt) for the domain name (abc.test.com) under the site (ZoneId is zone-2fgd17m17xw).

    Input Example

    POST / HTTP/1.1
    Host: teo.intl.tencentcloudapi.com
    Content-Type: application/json
    X-TC-Action: ModifyHostsCertificate
    <Common request parameters>
    
    {
        "ZoneId": "zone-2fgd17m17xw",
        "Hosts": [
            "abc.test.com"
        ],
        "Mode": "sslcert",
        "ServerCertInfo": [
            {
                "CertId": "J2JqATrt"
            }
        ]
    }
    

    Output Example

    {
        "Response": {
            "RequestId": "5e5a0d0f-52f3-4bad-9bd3-dcf1d5c954e7"
        }
    }
    

    Example2 Configuring a Free Certificate

    This example shows you how to configure a free certificate for the domain name (abc.test.com) under the site (ZoneId is zone-2fgd17m17xw).

    Input Example

    POST / HTTP/1.1
    Host: teo.intl.tencentcloudapi.com
    Content-Type: application/json
    X-TC-Action: ModifyHostsCertificate
    <Common request parameters>
    
    {
        "ZoneId": "zone-2fgd17m17xw",
        "Hosts": [
            "abc.test.com"
        ],
        "Mode": "eofreecert"
    }
    

    Output Example

    {
        "Response": {
            "RequestId": "084d5612-67a7-4aca-aac9-827aa3662b2d"
        }
    }
    

    Example3 Configuring the edge mutual authentication

    This example shows you how to configure the edge mutual authentication (CertId is J2JqATrt) for the domain name (abc.test.com) under the site (ZoneId is zone-2fgd17m17xw).

    Input Example

    POST / HTTP/1.1
    Host: teo.intl.tencentcloudapi.com
    Content-Type: application/json
    X-TC-Action: ModifyHostsCertificate
    <Common request parameters>
    
    {
        "ZoneId": "zone-2fgd17m17xw",
        "Hosts": [
            "abc.test.com"
        ],
        "ClientCertInfo": {
            "Switch": "on",
            "CertInfos": [
                {
                    "CertId": "J2JqATrt"
                }
            ]
        }
    }
    

    Output Example

    {
        "Response": {
            "RequestId": "5e5a0d0f-52f3-4bad-9bd3-dcf1d5c954e7"
        }
    }
    

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error CodeDescription
    FailedOperationOperation failed.
    FailedOperation.CertificateHasExpiredThe edge HTTPS certificate has expired. Issuing expired certificates is currently not supported.
    FailedOperation.CertificateNotFoundThe edge HTTPS certificate does not exist.
    FailedOperation.EdgeClientCertificateHasExpiredThe edge client certificate has expired. It is not supported to issue expired certificates for the time being.
    FailedOperation.InvalidZoneStatusThe site status is invalid.
    FailedOperation.ModifyFailedOperation failed.
    FailedOperation.UpstreamClientCertificateHasExpiredThe client certificate for the origin-pull mutual authentication has expired. It is not supported to issue expired certificates.
    InternalError.ConfigLockedThe configuration is locked. Please unlock and try again.
    InternalError.GetRoleErrorFailed to get the role.
    InternalError.ProxyServerAn unknown error occurred in the backend server.
    InternalError.RouteErrorThe backend routing address is incorrect.
    InternalError.SystemErrorInternal system error.
    InternalError.UnknowErrorUnknown error.
    InvalidParameter.ActionInProgressToo many attempts. Please try again later.
    InvalidParameter.AliasDomainNotSupportKeylessAlias domain names do not support configuring a keyless certificate.
    InvalidParameter.CertNotMatchDomainInvalid edge HTTPS certificate configuration. The certificate does not match the domain name.
    InvalidParameter.CertToExpireThe edge HTTPS certificate is about to expire.
    InvalidParameter.CertTooShortKeySizeInvalid edge HTTPS certificate configuration. The key length does not meet the minimum requirement RSA>=2048, DSA>=2048, DH>=2048, and EC>=225.
    InvalidParameter.CertificateConflictWithKeylessServerThe domain name to be changed is not bound to a certificate or keyless server. Please bind it first and then proceed.
    InvalidParameter.CnameWildHostNotAllowApplyCertificateUnable to apply for a wildcard certificate under CNAME mode.
    InvalidParameter.EdgeClientCertCheckErrorInvalid edge client certificate configuration.
    InvalidParameter.HostStatusNotAllowApplyCertificateCNAME is not switched or the origin is not routed to the EdgeOne server.
    InvalidParameter.InvalidCertInfoInvalid edge HTTPS certificate information.
    InvalidParameter.InvalidHttpsCertInfoInvalid edge HTTPS certificate configuration. The certificate content is invalid.
    InvalidParameter.InvalidHttpsTlsVersionInvalid HTTPS TLS version.
    InvalidParameter.UpstreamClientCertCheckErrorInvalid origin-pull client certificate configuration.
    InvalidParameter.ZoneIsGrayPublishingThe site is being upgraded. Changing is not supported. Please try again later.
    InvalidParameterValue.AliasDomainNotSupportEdgeMTLSAlias domain names do not support the configuration of edge mutual authentication for the time being.
    InvalidParameterValue.AliasDomainNotSupportUpstreamMTLSAlias domain names do not support the configuration of origin-pull mutual authentication for the time being.
    InvalidParameterValue.CertificateVerifyClientMustCa
    InvalidParameterValue.CertificateVerifyClientNeedCert
    InvalidParameterValue.CertificateVerifyUpstreamClientMustRSAorECCCurrently, only RSA or ECC algorithm certificates are supported for the origin-pull mutual authentication, and the SCA SM2 algorithm certificates are not supported.
    InvalidParameterValue.CertificateVerifyUpstreamClientMustSVRThe certificate type for the origin-pull mutual authentication is incorrect and cannot be configured as a CA certificate.
    InvalidParameterValue.CertificateVerifyUpstreamClientNeedCertOrigin-pull mutual authentication configuration requires at least one certificate.
    InvalidParameterValue.ClientCertInfoQuotaLimit
    InvalidParameterValue.InvalidKeylessServerIdInvalid keyless server ID.
    InvalidParameterValue.ServerCertInfoNeedContainRSAorECCEdge mTLS is enabled. When the client uses an RSA or ECC algorithm certificate, the same algorithm certificate should also be configured in the edge HTTPS certificate.
    InvalidParameterValue.ServerCertInfoNeedContainSM2Edge mTLS is enabled. When the client uses a national encryption CA certificate, the national encryption certificate should also be configured in the edge HTTPS certificate.
    InvalidParameterValue.UpstreamClientCertInfoQuotaLimitOne client certificate is allowed at most in the origin-pull mutual authentication configuration.
    LimitExceeded.RateLimitExceededReached the API rate limit.
    OperationDeniedOperation denied.
    OperationDenied.CertificatePrivateKeyIsEmptyCurrently, only the keyless certificate mode allows the private key of the certificate to be empty.
    OperationDenied.ConfigLockedThe configuration is locked. Please unlock and try again.
    OperationDenied.DisableZoneNotCompletedThe EdgeOne service of the site is being disabled. Please try again later.
    OperationDenied.ErrZoneIsAlreadyPausedThe EdgeOne service of the site is disabled. Please enable it and try again.
    OperationDenied.HostsClientCertificateInconsistencyThe edge mutual authentication certificates for the domain name to be changed are inconsistent. Please confirm that the domain name certificates are consistent and try again.
    OperationDenied.HostsKeylessServerInconsistencyThe keyless server of the domain name to be changed is inconsistent. Please confirm that the keyless server is consistent before retrying.
    OperationDenied.HostsUpstreamCertificateInconsistencyThe origin-pull mutual authentication certificates for the domain name to be changed are inconsistent. Please confirm that the domain name certificates are consistent and try again.
    OperationDenied.KeylessCertSwitchToFreeCertConflictThe domain name to be changed has a different certificate or keyless server. Please confirm that the edge HTTPS certificate or keyless server is consistent before retrying.
    OperationDenied.KeylessModeCertificatePrivateKeyNeedEmptyThe keyless certificate mode requires the private key of the certificate to be empty.
    OperationDenied.NotInKeylessWhiteListCurrently, the keyless certificate feature is available only to users in the allowlist.
    OperationDenied.NotInUpstreamMTLSWhiteListThe current origin-pull mutual authentication feature is only available to allowlist users.
    OperationDenied.UnSupportToCloseUpstreamMTLSDisabling the origin-pull mutual authentication is not supported now. To disable it, please change the edge HTTPS certificate configuration to 'none'.
    OperationDenied.UseUpstreamMTLSNeedOpenHttpsTo enable the origin-pull mutual authentication, please configure the edge HTTPS certificate first.
    OperationDenied.VersionControlIsGrayingThere is a test version in use. Please release the test version to the live environment, or roll back the test version and try again.
    ResourceInUseThe resource is occupied.
    ResourceUnavailable.CertNotFoundThe certificate does not exist or is not authorized.
    ResourceUnavailable.HostNotFoundThe domain name does not exist or not use a proxy.
    ResourceUnavailable.ZoneNotFoundThe site does not exist or is not belong to this account.
    UnauthorizedOperation.CamUnauthorizedCAM is not authorized.