Managing SSL certificates

VTEX Shield

Learn how to manage custom SSL certificates with VTEX Shield.

This feature is part of VTEX Shield. If you're a current VTEX customer and want to adopt VTEX Shield for your business, please contact Commercial Support. Additional fees may apply. If you're not a customer yet but are interested in this solution, please complete our contact form.

VTEX automatically manages SSL certificates for stores by default, but merchants may need to use their own certificates for specific compliance reasons, internal security requirements, or certification entities that offer additional warranties.

To give them a flexible and secure way to upload their certificates to our infrastructure, we offer the SSL Certificates API and the SSL certificates page in the Admin.

This guide explains how to use the API for managing certificates.

The SSL Certificates API allows users to list their custom SSL certificates, get a specific certificate by ID, and install or renew a certificate.

Before you begin

Make sure you meet the following prerequisites to manage SSL certificates:

You must have the Custom SSL certificates feature from VTEX Shield.
You must have a user or API key associated with a role that contains the following License Manager resources:
- Product: CDN API
- Category: Certificate management
- Resources: Update certificate and View certificate

Installing or renewing an SSL certificate

To install a certificate, you can send its information through an Install or renew SSL certificate PUT request, using multipart/form-data or application/json. The process of renewing a certificate is the same as the process of installing one.

Request example - multipart/form-data


_10curl --request PUT 'https://{{accountName}}.vtexcommercestable.com.br/api/edge/certificates' \
_10--header 'VtexIdclientAutCookie: {{VtexIdclientAutCookie}}' \
_10--form 'Hosts="{{MY_HOST}}"' \
_10--form 'Certificate=@"{{CERTIFICATE_PATH}}"' \
_10--form 'PrivateKey=@"{{PRIVATE_KEY_PATH}}"'

For the example account myaccountname and host mystore.com, the request should look like this:


_10curl --request PUT 'https://myaccountname.vtexcommercestable.com.br/api/edge/certificates' \
_10--header 'VtexIdclientAutCookie: {{VtexIdclientAutCookie}}' \
_10--form 'Hosts="mystore.com"' \
_10--form 'Certificate=@"/path/to/certificate.crt"' \
_10--form 'PrivateKey=@"/path/to/private.key"'

Request example - application/json


_10curl --request PUT 'https://{{accountName}}.vtexcommercestable.com.br/api/edge/certificates' \
_10--header 'VtexIdclientAutCookie: {{VtexIdclientAutCookie}}' \
_10--header 'Content-Type: application/json' \
_10--data '{
_10    "hosts": ["{{MY_HOST}}"],
_10    "certificate": "{{BASE64_ENCODED_CERTIFICATE}}",
_10    "privateKey": "{{BASE64_ENCODED_PRIVATE_KEY}}"
_10}'

For the example account myaccountname and host mystore.com, the request should look like this:


_10curl --request PUT 'https://myaccountname.vtexcommercestable.com.br/api/edge/certificates' \
_10--header 'VtexIdclientAutCookie: {{VtexIdclientAutCookie}}' \
_10--header 'Content-Type: application/json' \
_10--data '{
_10    "hosts": ["mystore.com"],
_10    "certificate": "LS0tLS1CRUd...S0tLS0K",
_10    "privateKey": "LS0tLS1CRUd...LS0NCg=="
_10}'

Response example

In both cases, whether installing or renewing a certificate, the response should look like this:


_23[
_23    {
_23        "id": "3421b2ea-94b1-55ac-67ea-e517018fbatc",
_23        "account": "myaccountname",
_23        "host": "mystore.com",
_23        "serialNumber": "99C468B5853EF5549E40A44526720C71GT",
_23        "subjectDistinguishedName": "CN=mystore.com",
_23        "subjectCommonName": "mystore.com",
_23        "subjectOrganization": null,
_23        "issuerDistinguishedName": "CN=ZeroSSL RSA Domain Secure Site CA, O=ZeroSSL, C=AT",
_23        "issuerCommonName": "ZeroSSL RSA Domain Secure Site CA",
_23        "issuerOrganization": "ZeroSSL",
_23        "installDate": "2025-04-24T20:15:51.7903622Z",
_23        "startDate": "2025-03-20T00:00:00Z",
_23        "expiryDate": "2025-06-18T23:59:59Z",
_23        "signatureAlgorithm": "sha384RSA",
_23        "x509Version": "3",
_23        "installedBy": "22b312e1-f863-43t7-8c59-5n2f9ll0d09x",
_23        "createdAt": "2025-03-20T13:20:34.40938Z",
_23        "updatedAt": "2025-04-24T20:15:51.7903892Z",
_23        "status": "Installing"
_23    }
_23]

Find more details about each field in the Install or renew SSL certificate PUT reference.

Listing SSL certificates

You can list your certificates with the List SSL certificates GET endpoint, as shown below. Remember to replace the accountName and VtexIdclientAutCookie placeholders.

Request example


_10curl 'https://{{accountName}}.vtexcommercestable.com.br/api/edge/certificates' \
_10--header 'VtexIdclientAutCookie: {{VtexIdclientAutCookie}}'

For the example account myaccountname, the request should look like this:


_10curl 'https://myaccountname.vtexcommercestable.com.br/api/edge/certificates' \
_10--header 'VtexIdclientAutCookie: 1234'

Response example


_23[
_23    {
_23        "id": "8c66122e-85cd-4bff-885d-aa9846e97541",
_23        "account": "myaccountname",
_23        "host": "mystore.com",
_23        "serialNumber": "05C51F848EDBAC18E91D9AE43D8F6728D4F8",
_23        "subjectDistinguishedName": "CN=mystore.com",
_23        "subjectCommonName": "mystore.com",
_23        "subjectOrganization": null,
_23        "issuerDistinguishedName": "CN=R10, O=Let's Encrypt, C=US",
_23        "issuerCommonName": "R10",
_23        "issuerOrganization": "Let's Encrypt",
_23        "installDate": "2025-04-22T16:24:58.768939Z",
_23        "startDate": "2024-08-29T01:43:25Z",
_23        "expiryDate": "2024-11-27T01:43:24Z",
_23        "signatureAlgorithm": "sha256RSA",
_23        "x509Version": "3",
_23        "installedBy": "22b312e1-f863-43t7-8c59-5n2f9ll0d09x",
_23        "createdAt": "2024-10-25T17:51:51.222052Z",
_23        "updatedAt": "2025-04-22T16:24:58.768939Z",
_23        "status": "Active"
_23    }
_23]

Find more details about each field in the List SSL certificates GET reference.

Getting an SSL certificate by its ID

To get a specific certificate, you can use the Get SSL certificate by ID GETrequest. Remember to replace theaccountNameandVtexIdclientAutCookie` placeholders.

Request example


_10curl 'https://{{accountName}}.vtexcommercestable.com.br/api/edge/certificates/{{certificateId}}' \
_10--header 'VtexIdclientAutCookie: {{VtexIdclientAutCookie}}'

For the example account myaccountname and certificate ID 8c66122e-85cd-4bff-885d-aa9846e97541, the request should look like this:


_10curl 'https://myaccountname.vtexcommercestable.com.br/api/edge/certificates/8c66122e-85cd-4bff-885d-aa9846e97541' \
_10--header 'VtexIdclientAutCookie: 1234'

Response example


_21{
_21    "id": "8c66122e-85cd-4bff-885d-aa9846e97541",
_21    "account": "myaccountname",
_21    "host": "mystore.com",
_21    "serialNumber": "05C51F848EDBAC18E91D9AE43D8F6728D4F8",
_21    "subjectDistinguishedName": "CN=mystore.com",
_21    "subjectCommonName": "mystore.com",
_21    "subjectOrganization": null,
_21    "issuerDistinguishedName": "CN=R10, O=Let's Encrypt, C=US",
_21    "issuerCommonName": "R10",
_21    "issuerOrganization": "Let's Encrypt",
_21    "installDate": "2025-04-22T16:24:58.768939Z",
_21    "startDate": "2024-08-29T01:43:25Z",
_21    "expiryDate": "2024-11-27T01:43:24Z",
_21    "signatureAlgorithm": "sha256RSA",
_21    "x509Version": "3",
_21    "installedBy": "22b312e1-f863-43t7-8c59-5n2f9ll0d09x",
_21    "createdAt": "2024-10-25T17:51:51.222052Z",
_21    "updatedAt": "2025-04-22T16:24:58.768939Z",
_21    "status": "Active"
_21}

Find more details about each field in the Get SSL certificate by ID GET reference.