TLS Certificate Management

The page introduces how to manage TLS certificates for a specific deployment using the EMQX Cloud API, including adding, viewing, updating, and deleting TLS certificate information.

This API applies to EMQX Dedicated and Dedicated Flex v5 deployments and EMQX v4 (4.4.x) deployments created under a Platform account. It does not support BYOC TLS certificate updates.

Certificate Input Requirements

• cert must contain one or more PEM-encoded X.509 version 1 or version 3 certificates. Place the server certificate first and intermediate certificates after it in issuing order. A chain can contain no more than five certificates.
• The server certificate must be currently valid and have at least 5 days remaining before expiration.
• Only whitespace is allowed between certificate blocks. Extra text, private-key blocks, incomplete blocks, and mismatched PEM markers are rejected.
• The certificate and its distinguished name (DN) must be correctly encoded. If the DN contains countryName, its value must be a two-character PrintableString. The certificate serial number must be zero or positive.
• MD5 signatures are not supported. A certificate followed by its issuer in the chain (the child certificate) must also not use SHA-1.
• For each adjacent pair in the submitted chain, the issuer name of the child certificate must match the subject name of the next certificate, and the child certificate's signature must be verifiable with the next certificate's public key.
• Each issuing certificate must be a CA certificate. If it contains a Key Usage extension, the extension must permit certificate signing.
• If the leaf certificate uses an EC public key, the supported curves are P-256, P-384, and P-521.
• key must be a passwordless PKCS#1 or PKCS#8 PEM private key that matches the server certificate.
• For two-way TLS, cacert is required. It can contain one or more trusted client CA certificates, each of which is validated separately. These certificates do not need to form an ordered chain. Only the server certificate chain is subject to these requirements: no more than five certificates, and at least 5 days of remaining validity for the first certificate.

The API validates certificate input before saving or applying a TLS/SSL configuration. If validation fails, the current certificate and configuration remain unchanged. Certificate validation errors return HTTP 400 and identify the request field, the certificate position in the input (starting from 1), and the reason.

Get TLS Certificate Status for Specified Deployment

URI

GET /deployments/{deployment_id}/tls

TIP

This method can only be requested 60 times in 60 minutes. {deployment_id} is the deployment ID, not the deployment name.

Request

None

Response

• 200:

Name	Type	Description
tlsType	String	TLS type：'one-way', 'two-way'.
expire	String	Certificate expiration date.
status	String	TLS certificate status: 'running' running, 'pending' creating.

• 401: API Key authentication failed.
• 403: API Key no access.
• 404: Deployment not found.
• 429: Request exceeds the limit.

Request Example

curl -u key:secret -X GET {api}/deployments/ge6a1a75/tls

Response Example

{
  "expire": "2034-05-22 02:43:21",
  "status": "running",
  "tlsType": "one-way"
}

Create TLS Certificates for Specified Deployment

URI

POST /deployments/{deployment_id}/tls

TIP

This method can only be requested 6 times in 60 minutes. {deployment_id} is the deployment ID, not the deployment name.

Request

Name	Type	Description
tlsType	String	TLS type：'one-way'，'two-way'。
cert	String	Public Key Certificates
key	String	Private key
cacert	String	Client CA certificate, need to upload when the certificate type is 'two-way'.

Response

• 201:

Name	Type	Description
tlsType	String	TLS type：'one-way'，'two-way'.
expire	String	Certificate expiration date.
status	String	TLS certificate status: 'running' running, 'pending' creating.

• 400: The certificate, chain, validity period, private key, or key/certificate match is invalid.
• 401: API Key authentication failed.
• 403: API Key no access.
• 404: Deployment not found.
• 422: A required field is missing or a request property is invalid. cacert is required when tlsType is two-way.
• 429: Request exceeds the limit.

Request Example

curl -u key:secret \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "tlsType": "one-way",
    "cert": "-----BEGIN CERTIFICATE-----\nMII...tH6j7afSg==\n-----END CERTIFICATE-----",
    "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA5bdg8Rt5A7...AjQzYRdov4inpzw==\n-----END RSA PRIVATE KEY-----"
  }' \
  {api}/deployments/ge6a1a75/tls

Response Example

{
  "expire": "2034-05-22 02:43:21",
  "status": "pending",
  "tlsType": "one-way"
}

Update TLS Certificates for Specified Deployment

URI

PUT /deployments/{deployment_id}/tls

TIP

This method can only be requested 6 times in 60 minutes. {deployment_id} is the deployment ID, not the deployment name.

Request

Name	Type	Description
tlsType	String	TLS type：'one-way'，'two-way'。
cert	String	Public Key Certificates
key	String	Private key
cacert	String	Client CA certificate, need to upload when the certificate type is 'two-way'.

Response

• 200:

Name	Type	Description
tlsType	String	TLS type：'one-way'，'two-way'.
expire	String	Certificate expiration date.
status	String	TLS certificate status: 'running' running, 'pending' creating.

• 400: The certificate, chain, validity period, private key, or key/certificate match is invalid.
• 401: API Key authentication failed.
• 403: API Key no access.
• 404: Deployment not found.
• 422: A required field is missing or a request property is invalid. cacert is required when tlsType is two-way.
• 429: Request exceeds the limit.

Request Example

curl -u key:secret \
  -X PUT \
  -H 'Content-Type: application/json' \
  -d '{
    "tlsType": "one-way",
    "cert": "-----BEGIN CERTIFICATE-----\nMII...tH6j7afSg==\n-----END CERTIFICATE-----",
    "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA5bdg8Rt5A7...AjQzYRdov4inpzw==\n-----END RSA PRIVATE KEY-----"
  }' \
  {api}/deployments/ge6a1a75/tls

Response Example

{
  "expire": "2034-05-22 02:43:21",
  "status": "pending",
  "tlsType": "one-way"
}

Delete TLS Certificates for Specified Deployment

URI

DELETE /deployments/{deployment_id}/tls

TIP

This method can only be requested 6 times in 60 minutes. {deployment_id} is the deployment ID, not the deployment name.

Request

None

Response

• 401: API Key authentication failed.
• 403: API Key no access.
• 404: Deployment not found.
• 429: Request exceeds the limit.

Request Example

curl -u key:secret -X DELETE {api}/deployments/ge6a1a75/tls

Response Example

// HTTP status response code
204