Skip to Content

Add a Certificate

Add a certificate to the PBX by either importing an existing certificate file or directly apply for a new certificate.

Limitations

The PBX supports up to 3 PBX server certificates and 20 trusted CA certificates.

Request URL

POST {base_url}/{api_path}/certificate/create?access_token={access_token}

Request parameters

ParameterRequiredTypeDescription
typeYesStringCertificate type.
Valid value:
  • trusted: Trusted CA certificate.
  • server: PBX server certificate.
ca_typeNoStringThe method to add certificate.
Valid value:
  • upload: Import an existing certificate.
  • apply: Apply for a new certificate.
  • This parameter is required when type is set to server.
  • To import a certificate, make sure you have uploaded the desired certificate to the PBX's temporary storage area first.
Note:
nameNoStringCertificate file name.
Note:

  • This parameter is required when importing an existing certificate, including the following scenarios:

    • type is set to trusted.
    • type is set to server and ca_type is set to upload.
  • You can obtain the file name from the file field in the response of Upload a Certificate API call.
issue_toNoStringThe domain name to be associated with the certificate.
Note: This parameter is required when applying for a certificate (type is set to server and ca_type is set to apply).
auto_renewalNoIntegerWhether to enable auto-renewal for the imported PBX server certificate.
Valid value:
  • 0: Disable.
  • 1: Enable.
Note:This parameter takes effect only when type is set to server and ca_type is set to upload.
dns_providerNoStringThe DNS provider used for certificate application and auto-renewal.
Note:

  • This parameter is required in the following scenarios:

    • auto_renewal is set to 1.
    • type is set to server and ca_type is set to apply.
  • For valid values, refer to the in the Flag Name column in Supported DNS Providers.
auth_info_listNoArray<Auth_Info>The DNS authentication information required for certificate application and auto-renewal.
Note:This parameter is required in the following scenarios:
  • auto_renewal is set to 1.
  • type is set to server and ca_type is set to apply.

Auth_Info

Note:

  • You MUST provide the complete set of parameters required by the selected DNS provider; otherwise, the request will fail.
  • For the authentication parameters and their value types of each DNS provider, see Supported DNS Providers.
ParameterRequiredTypeDescription
kYesStringThe key for the authentication parameter as defined by the DNS provider.
ivNoIntegerThe integer-format value of the authentication parameter.
svNoStringThe string-format value of the authentication parameter.
bvNoBooleanThe boolean-format value of the authentication parameter.

Response parameters

ParameterTypeDescription
errcodeIntegerReturned error code.
  • 0: Succeed.
  • Non-zero value: Failed.
Note: You can check the error code and error message in Error Code and Error Message.
errmsgStringReturned message.
  • SUCCESS: Succeed.
  • FAILURE: Failed.
nameStringThe name of the certificate.
apply_statusStringThe current application status of the certificate.
  • issuing: In progress.
  • issuance_success: Successfully issued.
  • issuance_fail: Failed.

Examples

The following examples are provided for different scenarios:

Add a trusted certificate to the PBX

  1. Upload the certificate to the PBX's temporary storage area.

    Request example

    POST /openapi/v1.0/certificate/upload?access_token=wOODrqhysk0aELacF87qd4lBvmbBY4IZ HTTP/1.1
Host: 192.168.5.150:8088

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="type"

trusted
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="/D:/project/certificate/example.domain.com.crt"
Content-Type: <Content-Type header here>

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

    Response example

    HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "file": "example.domain.com.crt"
}

  2. Add the certificate to the PBX.

    Request example

    POST /openapi/v1.0/certificate/create?access_token=wTZBgrTvaWMNid53Vzbi1FE92E9qnrVg HTTP/1.1
Host: 192.168.5.150:8088
Content-Type: application/json
{
    "type": "trusted",                  
    "name": "example.domain.com.crt"                 
}

    Response example

    HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "name": "example.domain.com.crt",
    "apply_status": "issuance_success"
}

Apply for a new certificate

Request example

POST /openapi/v1.0/certificate/create?access_token=wTZBgrTvaWMNid53Vzbi1FE92E9qnrVg HTTP/1.1
Host: 192.168.5.150:8088
Content-Type: application/json
{
    
    "type": "server",                  
    "ca_type": "apply",              
    "issue_to": "docstest.example.com",     
    "dns_provider": "alidns",         
    "auth_info_list": [      
        {
            "k": "AccessKeyId",
            "sv": "AKIAIXXXXXXXXXXAMPLE"
        },
        {
            "k": "AccessKeySecret",
            "sv": "wJalrXUXXXXXXXXXXLEKEY"
        },
        {
            "k": "PropagationTimeout",
            "iv": 300
        },
        {
            "k": "PollingInterval",
            "iv": 5
        },
        {
            "k": "TTL",
            "iv": 600
        }
    ]
}

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "name": "docstest.example.com.pem",
    "apply_status": "issuing"
}