tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

ModifyHostsCertificate

Last updated: 2024-12-03 16:17:53

    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 Name Required Type Description
    Action Yes String Common Params. The value used for this API: ModifyHostsCertificate.
    Version Yes String Common Params. The value used for this API: 2022-09-01.
    Region No String Common Params. This parameter is not required.
    ZoneId Yes String ID of the site.
    Hosts.N Yes Array of String Domain names that you need to modify the certificate configuration
    Mode No String Certificate configuration mode. Values:
  • disable: (Default) Do not configure the certificate
  • eofreecert: Use a free certificate provided by EdgeOne
  • sslcert: Configure an SSL certificate.
    		•
    ServerCertInfo.N No Array of ServerCertInfo SSL 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.
    ClientCertInfo No MutualTLS In 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 Name Type Description
    RequestId String The 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 Code Description
    FailedOperation Operation failed.
    FailedOperation.CertificateHasExpired The edge HTTPS certificate has expired. Issuing expired certificates is currently not supported.
    FailedOperation.CertificateNotFound The edge HTTPS certificate does not exist.
    FailedOperation.EdgeClientCertificateHasExpired The edge client certificate has expired. It is not supported to issue expired certificates for the time being.
    FailedOperation.InvalidZoneStatus The site status is invalid.
    FailedOperation.ModifyFailed Operation failed.
    FailedOperation.UpstreamClientCertificateHasExpired The client certificate for the origin-pull mutual authentication has expired. It is not supported to issue expired certificates.
    InternalError.ConfigLocked The configuration is locked. Please unlock and try again.
    InternalError.GetRoleError Failed to get the role.
    InternalError.ProxyServer An unknown error occurred in the backend server.
    InternalError.RouteError The backend routing address is incorrect.
    InternalError.SystemError Internal system error.
    InternalError.UnknowError Unknown error.
    InvalidParameter.ActionInProgress Too many attempts. Please try again later.
    InvalidParameter.AliasDomainNotSupportKeyless Alias domain names do not support configuring a keyless certificate.
    InvalidParameter.CertNotMatchDomain Invalid edge HTTPS certificate configuration. The certificate does not match the domain name.
    InvalidParameter.CertToExpire The edge HTTPS certificate is about to expire.
    InvalidParameter.CertTooShortKeySize Invalid edge HTTPS certificate configuration. The key length does not meet the minimum requirement RSA>=2048, DSA>=2048, DH>=2048, and EC>=225.
    InvalidParameter.CertificateConflictWithKeylessServer The domain name to be changed is not bound to a certificate or keyless server. Please bind it first and then proceed.
    InvalidParameter.CnameWildHostNotAllowApplyCertificate Unable to apply for a wildcard certificate under CNAME mode.
    InvalidParameter.EdgeClientCertCheckError Invalid edge client certificate configuration.
    InvalidParameter.HostStatusNotAllowApplyCertificate CNAME is not switched or the origin is not routed to the EdgeOne server.
    InvalidParameter.InvalidCertInfo Invalid edge HTTPS certificate information.
    InvalidParameter.InvalidHttpsCertInfo Invalid edge HTTPS certificate configuration. The certificate content is invalid.
    InvalidParameter.InvalidHttpsTlsVersion Invalid HTTPS TLS version.
    InvalidParameter.UpstreamClientCertCheckError Invalid origin-pull client certificate configuration.
    InvalidParameter.ZoneIsGrayPublishing The site is being upgraded. Changing is not supported. Please try again later.
    InvalidParameterValue.AliasDomainNotSupportEdgeMTLS Alias domain names do not support the configuration of edge mutual authentication for the time being.
    InvalidParameterValue.AliasDomainNotSupportUpstreamMTLS Alias domain names do not support the configuration of origin-pull mutual authentication for the time being.
    InvalidParameterValue.CertificateVerifyClientMustCa
    InvalidParameterValue.CertificateVerifyClientNeedCert
    InvalidParameterValue.CertificateVerifyUpstreamClientMustRSAorECC Currently, only RSA or ECC algorithm certificates are supported for the origin-pull mutual authentication, and the SCA SM2 algorithm certificates are not supported.
    InvalidParameterValue.CertificateVerifyUpstreamClientMustSVR The certificate type for the origin-pull mutual authentication is incorrect and cannot be configured as a CA certificate.
    InvalidParameterValue.CertificateVerifyUpstreamClientNeedCert Origin-pull mutual authentication configuration requires at least one certificate.
    InvalidParameterValue.ClientCertInfoQuotaLimit
    InvalidParameterValue.InvalidKeylessServerId Invalid keyless server ID.
    InvalidParameterValue.ServerCertInfoNeedContainRSAorECC Edge 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.ServerCertInfoNeedContainSM2 Edge 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.UpstreamClientCertInfoQuotaLimit One client certificate is allowed at most in the origin-pull mutual authentication configuration.
    LimitExceeded.RateLimitExceeded Reached the API rate limit.
    OperationDenied Operation denied.
    OperationDenied.CertificatePrivateKeyIsEmpty Currently, only the keyless certificate mode allows the private key of the certificate to be empty.
    OperationDenied.ConfigLocked The configuration is locked. Please unlock and try again.
    OperationDenied.DisableZoneNotCompleted The EdgeOne service of the site is being disabled. Please try again later.
    OperationDenied.ErrZoneIsAlreadyPaused The EdgeOne service of the site is disabled. Please enable it and try again.
    OperationDenied.HostsClientCertificateInconsistency The 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.HostsKeylessServerInconsistency The keyless server of the domain name to be changed is inconsistent. Please confirm that the keyless server is consistent before retrying.
    OperationDenied.HostsUpstreamCertificateInconsistency The 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.KeylessCertSwitchToFreeCertConflict The 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.KeylessModeCertificatePrivateKeyNeedEmpty The keyless certificate mode requires the private key of the certificate to be empty.
    OperationDenied.NotInKeylessWhiteList Currently, the keyless certificate feature is available only to users in the allowlist.
    OperationDenied.NotInUpstreamMTLSWhiteList The current origin-pull mutual authentication feature is only available to allowlist users.
    OperationDenied.UnSupportToCloseUpstreamMTLS Disabling the origin-pull mutual authentication is not supported now. To disable it, please change the edge HTTPS certificate configuration to 'none'.
    OperationDenied.UseUpstreamMTLSNeedOpenHttps To enable the origin-pull mutual authentication, please configure the edge HTTPS certificate first.
    OperationDenied.VersionControlIsGraying There is a test version in use. Please release the test version to the live environment, or roll back the test version and try again.
    ResourceInUse The resource is occupied.
    ResourceUnavailable.CertNotFound The certificate does not exist or is not authorized.
    ResourceUnavailable.HostNotFound The domain name does not exist or not use a proxy.
    ResourceUnavailable.ZoneNotFound The site does not exist or is not belong to this account.
    UnauthorizedOperation.CamUnauthorized CAM is not authorized.
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy