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

Parameter Required Type Description
type Yes String Certificate type.
Valid value:
  • trusted: Trusted CA certificate.
  • server: PBX server certificate.
ca_type No String The method to add certificate.
Valid value:
  • upload: Import an existing certificate.
  • apply: Apply for a new certificate.
Note:
  • 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.
name No String Certificate 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_to No String The 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_renewal No Integer Whether 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_provider No String The 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_list No Array<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.
Parameter Required Type Description
k Yes String The key for the authentication parameter as defined by the DNS provider.
iv No Integer The integer-format value of the authentication parameter.
sv No String The string-format value of the authentication parameter.
bv No Boolean The boolean-format value of the authentication parameter.

Response parameters

Table 1.
Parameter Type Description
errcode Integer Returned error code.
  • 0: Succeed.
  • Non-zero value: Failed.
Note: You can check the error code and error message in Error Code and Error Message.
errmsg String Returned message.
  • SUCCESS: Succeed.
  • FAILURE: Failed.
name String The name of the certificate.
apply_status String
The 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"
}