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 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 | Configures the mode of the server certificate. valid values:. Disables server-side certificate configuration. -In ns or DNSPod hosting access mode, free certificates can only be applied for via automatic validation. -When the free certificate application fails, it can cause certificate deployment failure. you can obtain the reason for the application failure through the check free certificate application result api. eofreecert_manual: specifies the deployment of a free certificate applied through DNS delegation verification or file verification. before deploying the free certificate, you need to trigger the apply for free certificate API to apply for a free certificate. once the application is successful, you can use this enumeration value to deploy the free certificate. Note: during deployment of a free certificate, ensure a successful application for a free certificate already exists. you can check whether a successful application for a free certificate already exists through the check free certificate application result api. sslcert: specifies the managed service side certificate configuration. |
| 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. |
| UpstreamCertInfo | No | UpstreamCertInfo | Specifies whether to enable/disable origin-pull mutual authentication and origin certificate verification. off by default. leave blank to indicate retaining the original configuration. the origin-pull mutual authentication configuration is currently in internal allowlist testing. if needed, please contact us (https://www.tencentcloud.comom/online?from_cn_redirect=1-service). |
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.
- Tencent Cloud SDK 3.0 for Python
- Tencent Cloud SDK 3.0 for Java
- Tencent Cloud SDK 3.0 for PHP
- Tencent Cloud SDK 3.0 for Go
- Tencent Cloud SDK 3.0 for Node.js
- Tencent Cloud SDK 3.0 for .NET
- Tencent Cloud SDK 3.0 for C++
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. |
| FailedOperation.UpstreamVerifyCustomCACertificateHasExpired | The origin CA certificate has expired. it is currently 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.UpstreamVerifyCertCheckError | Invalid origin certificate verification configuration. |
| InvalidParameter.UpstreamVerifyCustomCACertNoInfo | Invalid origin certificate verification configuration. certificate content is empty. |
| 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.AliasDomainNotSupportUpstreamVerify | Alias domain names do not support the configuration of origin certificate verification for the time being. |
| InvalidParameterValue.CertificateVerifyClientMustCa | The client certificate in the edge mTLS configuration must be a CA certificate. |
| InvalidParameterValue.CertificateVerifyClientNeedCert | Edge mTLS configuration requires at least one certificate. |
| 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.CertificateVerifyUpstreamVerifyCustomCAMustCA | The certificate type for origin certificate verification is incorrect. only CA certificates are supported. |
| InvalidParameterValue.CertificateVerifyUpstreamVerifyCustomCAMustRSAorECC | Currently, only RSA or ECC algorithm certificates are supported for origin certificate verification. the SM2 algorithm certificates are not supported. |
| InvalidParameterValue.CertificateVerifyUpstreamVerifyCustomCANeedCert | Origin certificate verification configuration requires at least one certificate. |
| InvalidParameterValue.ClientCertInfoQuotaLimit | The client CA certificate in edge mTLS configuration allows a maximum of 20 certificates. |
| InvalidParameterValue.InvalidKeylessServerId | Invalid keyless server ID. |
| InvalidParameterValue.OCDirectOriginDomainNotSupportUpstreamVerify | OC switching does not support enabling origin certificate verification. |
| 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. |
| InvalidParameterValue.UpstreamVerifyCustomCACertInfoQuotaLimit | Origin certificate verification configuration allows up to one CA certificate. |
| 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.HostsUpstreamCertificateVerifyInconsistency | The origin certificate verification for the domain name to be changed is inconsistent. please confirm the domain name is configured the same 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. |