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

When making requests to VTEX services using mTLS, VTEX validates whether the certificate was issued and signed by its internal Certificate Authority (CA). This guide walks you through the process of obtaining and managing certificates for mTLS authentication.

The first step is to generate a Certificate Signing Request (CSR) using OpenSSL 3.0.0 or higher. This process generates the CSR (.csr) and private key (.key) files.

Open a terminal and run the command below, replacing the values in {{ }} with your specific information:

The fields CN (Common Name) and OU (Organizational Unit) are mandatory and must contain the application name and account name, respectively.

Save both generated files (.csr and .key) for the next step.

Once you've generated the CSR, use the POST Sign certificate endpoint to request a certificate signed by VTEX's Certificate Authority. This request allows you to submit a CSR and receive a signed certificate.

To use this endpoint, your user or API key must have access to the following License Manager resource. Otherwise, a 403 status code error will be returned.

There are no predefined roles for these resources. To use this endpoint, you must create a custom role and add the above resource. Learn more about roles and resources in the Roles documentation.

The request body should contain the previously generated CSR as plain text:

The account in the request must match the one specified in the OU field of the CSR.

If successful, the API responds with the certificate in plain text:

Save this content to a .crt file. You'll use it along with the private key (.key) to authenticate requests.

Learn more in the POST Sign certificate API reference.

With the certificate issued, you can now authenticate your requests to VTEX using mTLS. See examples using Postman and cURL below.

To test mTLS requests with Postman, attach your certificate and private key directly in the tool's settings. Follow the steps below:

1. Open Postman and go to Settings.
2. Navigate to the Certificates tab.
3. Define the Host for the call.
4. In CRT file, add the certificate file (.crt).
5. In KEY file, add the private key (.key file generated earlier with the CSR).
6. Click Add to save the certificate configuration.

Once configured, any request made to the specified host will automatically include the certificate, allowing you to test mTLS-protected endpoints.

If you prefer to test or integrate mTLS requests via the command line, you can use cURL to send requests with your certificate and private key.

Use the following example to authenticate a request with mTLS:

Replace {{client.crt}} and {{client.key}} with the paths to your certificate and private key files, and insert a valid token in the request body.