Manage SSL certificates

SSL certificates secure the panel over HTTPS, SIP calls over TLS and STIR/SHAKEN signing. You either upload your own certificate and key, or let the switch obtain one from Let’s Encrypt. These methods do the same as System Management → SSL Management → SSL Certificates in the panel. They are available to the root customer.

All methods support trusted mode with i_customer; pass 1, the root customer.

On a multi-tenant switch every method takes an optional i_environment. With the ID of another environment, the request is relayed to that environment and the response has an extra relay_result struct with that environment’s answer.

SSL certificate structure

The fields of a certificate, as createSSLCertificate takes them and getSSLCertificateInfo returns them:

Name	Type	Description
i_ssl_certificate	int	ID of the certificate. Returned only
name	string	Name of the certificate
common_name	string	Common name (CN), the host name the certificate is for, for example sip.example.com
i_ssl_certificate_type	int	1 Upload Own: you supply the certificate and key; 2 Lets Encrypt: the switch obtains and renews the certificate. The ssl_certificate_types dictionary of getDictionary lists the values
i_ssl_use_domain_type	int	What the certificate is used for, Use Domain in the panel: 1 Web/HTTPS, 2 SIP TLS, 3 STIR/SHAKEN
alt_dns_names	array	Subject alternative names, an array of strings
certificate	string	The certificate in PEM format, base64-encoded
key	string	The private key in PEM format, base64-encoded
meta_data	string	Returned only. A JSON object with details of the certificate, including expiration_date

Which fields createSSLCertificate needs depends on the type:

Field	Upload Own	Lets Encrypt
name, common_name	required	required
i_ssl_certificate_type	optional	required
certificate, key	required	optional
alt_dns_names, i_ssl_use_domain_type, i_environment	optional	optional

For Let’s Encrypt, common_name must resolve to the switch, and the switch must be reachable from the internet on TCP port 80. See TLS certificates.

createSSLCertificate

Creates a certificate.

Parameters

Name	Type	Required	Description
name	string	yes	Name of the certificate
common_name	string	yes	Common name (CN)
i_ssl_certificate_type	int	no	Type of the certificate. Default: 1 Upload Own
i_ssl_use_domain_type	int	no	What the certificate is used for
alt_dns_names	array	no	Subject alternative names
certificate	string	one of	Base64 PEM certificate; required for Upload Own
key	string	one of	Base64 PEM private key; required for Upload Own
i_environment	int	no	Environment to create the certificate in

Returns

Name	Type	Description
result	string	OK
i_ssl_certificate	int	ID of the new certificate
relay_result	struct	Answer of the other environment; only when i_environment names another environment

Example

Ask the switch for a Let’s Encrypt certificate for SIP TLS:

request

call("createSSLCertificate", {
    "i_customer": 1,
    "name": "SIP TLS",
    "common_name": "sip.example.com",
    "i_ssl_certificate_type": 2,
    "i_ssl_use_domain_type": 2,
    "alt_dns_names": ["sip2.example.com"],
})

response

{"result": "OK", "i_ssl_certificate": 7}

updateSSLCertificate

Changes a certificate. Fields you do not pass keep their values.

Parameters

Name	Type	Required	Description
i_ssl_certificate	int	yes	ID of the certificate
name	string	no	New name
common_name	string	no	New common name
i_ssl_certificate_type	int	no	New type
i_ssl_use_domain_type	int	no	New use
alt_dns_names	array	no	New subject alternative names; replaces the old list
certificate	string	no	New base64 PEM certificate
key	string	no	New base64 PEM private key
i_environment	int	no	Environment the certificate is in

Returns

Name	Type	Description
result	string	OK
i_ssl_certificate	int	ID of the certificate
relay_result	struct	Answer of the other environment, when relayed

Example

Replace an uploaded certificate before it expires:

request

import base64


def b64(path):
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode()


call("updateSSLCertificate", {
    "i_customer": 1,
    "i_ssl_certificate": 3,
    "certificate": b64("panel.example.com.crt"),
    "key": b64("panel.example.com.key"),
})

response

{"result": "OK", "i_ssl_certificate": 3}

deleteSSLCertificate

Deletes a certificate.

Parameters

Name	Type	Required	Description
i_ssl_certificate	int	yes	ID of the certificate
i_environment	int	no	Environment the certificate is in

Returns

Name	Type	Description
result	string	OK
i_ssl_certificate	int	ID of the deleted certificate
relay_result	struct	Answer of the other environment, when relayed

Example

request

call("deleteSSLCertificate", {"i_customer": 1, "i_ssl_certificate": 7})

response

{"result": "OK", "i_ssl_certificate": 7}

getSSLCertificateInfo

Returns one certificate.

Parameters

Name	Type	Required	Description
i_ssl_certificate	int	yes	ID of the certificate
i_environment	int	no	Environment the certificate is in

Returns

Name	Type	Description
result	string	OK
ssl_certificate	struct	The fields of the SSL certificate structure
relay_result	struct	Answer of the other environment, when relayed

Example

request

call("getSSLCertificateInfo", {"i_customer": 1, "i_ssl_certificate": 3})

response

{
    "result": "OK",
    "ssl_certificate": {
        "i_ssl_certificate": 3,
        "name": "Panel",
        "common_name": "panel.example.com",
        "i_ssl_certificate_type": 1,
        "i_ssl_use_domain_type": 1,
        "alt_dns_names": [],
        "certificate": "LS0tLS1CRUdJTi…",
        "key": "LS0tLS1CRUdJTi…",
        "meta_data": '{"expiration_date": "2026-04-15T12:00:00+00:00"}',  # … other details
    },
}

getSSLCertificatesList

Returns certificates, optionally filtered by name.

Parameters

Name	Type	Required	Description
name_pattern	string	no	Filter by name, SQL ILIKE syntax: % matches any text, the match ignores case
limit	int	no	Maximum number of certificates to return
offset	int	no	Number of certificates to skip
i_environment	int	no	Environment to list the certificates of

Returns

Name	Type	Description
result	string	OK
ssl_certificates	array	Certificates, each a struct as getSSLCertificateInfo returns it
relay_result	struct	Answer of the other environment, when relayed

Example

request

call("getSSLCertificatesList", {"i_customer": 1, "limit": 20, "offset": 0})

response

{
    "result": "OK",
    "ssl_certificates": [
        {"i_ssl_certificate": 3, "name": "Panel", "common_name": "panel.example.com"},  # … all fields
    ],
}

Tip

To warn about expiring certificates, call getSSLCertificatesList once a day and parse expiration_date from meta_data. The panel flags a certificate that expires within 28 days.

Related

• TLS certificates: Let’s Encrypt certificates in the panel
• Authorization and termination of TLS traffic
• Manage CA lists