diff --git a/VTEX - SSL Certificates API.json b/VTEX - SSL Certificates API.json new file mode 100644 index 000000000..227f21576 --- /dev/null +++ b/VTEX - SSL Certificates API.json @@ -0,0 +1,643 @@ +{ + "openapi": "3.0.0", + "info": { + "version": "1.0", + "title": "SSL Certificates API", + "description": "The SSL Certificates API allows VTEX users to programmatically manage SSL certificates for their store domains. It enables users to list all installed certificates and install or renew certificates using JSON or multipart form data.\r\n\r\nThe API provides detailed metadata about each certificate, including issuer, subject, validity period, installation status, and more. This helps ensure secure HTTPS connections for custom domains, automating certificate lifecycle management and supporting integration with external certificate authorities or automation tools.\r\n\r\n>ℹ️ Learn more about [Custom SSL certificates](https://help.vtex.com/en/tutorial/custom-ssl-certificates--1hoaDEbU50PDZSe6AYep9q).\r\n\r\n>ℹ️ This feature is part of [VTEX Shield](https://help.vtex.com/en/tutorial/vtex-shield--2CVk6H9eY2CBtHjtDI7BFh). If you are already a VTEX customer and want to adopt VTEX Shield for your business, please contact [Commercial Support](https://help.vtex.com/en/tracks/support-at-vtex--4AXsGdGHqExp9ZkiNq9eMy/3KQWGgkPOwbFTPfBxL7YwZ). Additional fees may apply. If you are not yet a customer but are interested in this solution, please complete our [contact form](https://vtex.com/br-pt/contato/).\r\n\r\n## Index\r\n\r\n### SSL Certificates\r\n\r\n- `GET` [List SSL certificates](https://developers.vtex.com/docs/api-reference/ssl-certificates-api#get-/api/edge/certificates)\r\n- `GET` [Get SSL certificate by ID](https://developers.vtex.com/docs/api-reference/ssl-certificates-api#get-/api/edge/certificates/-certificateId-)\r\n- `PUT` [Install or renew SSL certificate](https://developers.vtex.com/docs/api-reference/ssl-certificates-api#put-/api/edge/certificates)\r\n\r\n## Common parameters\r\n\r\n| Parameter name | Description | Type |\r\n|-|-|-|\r\n| `{{accountName}}` | Name of the VTEX account. Used as part of the URL. | Server variable |\r\n| `{{environment}}` | Environment to use. Used as part of the URL. The default value is `vtexcommercestable`. | Server variable |\r\n| `X-VTEX-API-AppKey` | Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys). | Authentication header |\r\n| `X-VTEX-API-AppToken` | Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys). | Authentication header |\r\n| `VtexIdclientAutCookie` | [User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours. | Authentication header |\r\n" + }, + "servers": [ + { + "url": "https://{accountName}.{environment}.com.br", + "description": "VTEX server URL.", + "variables": { + "accountName": { + "description": "Name of the VTEX account. Used as part of the URL", + "default": "apiexamples" + }, + "environment": { + "description": "Environment to use. Used as part of the URL.", + "enum": [ + "vtexcommercestable" + ], + "default": "vtexcommercestable" + } + } + } + ], + "paths": { + "/api/edge/certificates": { + "get": { + "tags": [ + "SSL Certificates" + ], + "summary": "List SSL certificates", + "description": "Retrieves a list of SSL certificates.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| CDN API | Certificate management | **View certificate** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "parameters": [ + { + "$ref": "#/components/parameters/Content-Type" + }, + { + "$ref": "#/components/parameters/Accept" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "description": "List of SSL certificates.", + "items": { + "type": "object", + "description": "Information about each SSL certificate.", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the certificate.", + "nullable": false + }, + "account": { + "type": "string", + "description": "Account name associated with the certificate.", + "nullable": false + }, + "host": { + "type": "string", + "description": "Primary host/domain of the certificate.", + "nullable": false + }, + "serialNumber": { + "type": "string", + "description": "Certificate serial number.", + "nullable": false + }, + "subjectDistinguishedName": { + "type": "string", + "description": "Full distinguished name of the subject.", + "nullable": false + }, + "subjectCommonName": { + "type": "string", + "description": "Common name (CN) of the certificate subject.", + "nullable": false + }, + "subjectOrganization": { + "type": "string", + "description": "Organization (O) of the certificate subject.", + "nullable": true + }, + "issuerDistinguishedName": { + "type": "string", + "description": "Full distinguished name of the issuing certificate authority.", + "nullable": false + }, + "issuerCommonName": { + "type": "string", + "description": "Common name (CN) of the certificate issuer.", + "nullable": false + }, + "issuerOrganization": { + "type": "string", + "description": "Organization (O) of the certificate issuer.", + "nullable": false + }, + "installDate": { + "type": "string", + "description": "Timestamp when the certificate was installed in ISO 8601 format.", + "nullable": false + }, + "startDate": { + "type": "string", + "description": "Certificate validity start date in ISO 8601 format.", + "nullable": false + }, + "expiryDate": { + "type": "string", + "description": "Certificate expiry date in ISO 8601 format.", + "nullable": false + }, + "signatureAlgorithm": { + "type": "string", + "description": "Algorithm used to sign the certificate.", + "nullable": false + }, + "x509Version": { + "type": "string", + "description": "X.509 version of the certificate.", + "nullable": false + }, + "installedBy": { + "type": "string", + "description": "ID of the user that installed the certificate.", + "nullable": false + }, + "createdAt": { + "type": "string", + "description": "Creation timestamp of the certificate entry in ISO 8601 format.", + "nullable": false + }, + "updatedAt": { + "type": "string", + "description": "Timestamp of the last certificate update in ISO 8601 format.", + "nullable": false + }, + "status": { + "type": "string", + "description": "Current status of the certificate, which can be one of the following:\n\n- **Active**: Valid and active for the host.\n- **Overwritten**: The certificate for this host has been replaced by another through an external method, such as an API call on the CDN.\n- **Installing**: Certificate installation in progress.\n- **Unknown**: The certificate status couldn't be determined due to internal technical problems with communication, configuration, or monitoring.\n- **Expires soon**: The certificate is close to its expiration date (30 days before or less).\n- **Installation failed**: After the status Installing, the installation can fail, and the user will need to try again later.\n- **Expired**: The expiration date passed.", + "nullable": false, + "enum": [ + "Active", + "Overwritten", + "Installing", + "Unknown", + "Expires soon", + "Installation failed", + "Expired" + ] + } + } + } + }, + "example": [ + { + "id": "8c66122e-85cd-4bff-885d-aa9846e97541", + "account": "myaccountname", + "host": "mystore.com", + "serialNumber": "05C51F848EDBAC18E91D9AE43D8F6728D4F8", + "subjectDistinguishedName": "CN=mystore.com", + "subjectCommonName": "mystore.com", + "subjectOrganization": null, + "issuerDistinguishedName": "CN=R10, O=Let's Encrypt, C=US", + "issuerCommonName": "R10", + "issuerOrganization": "Let's Encrypt", + "installDate": "2025-04-22T16:24:58.768939Z", + "startDate": "2024-08-29T01:43:25Z", + "expiryDate": "2024-11-27T01:43:24Z", + "signatureAlgorithm": "sha256RSA", + "x509Version": "3", + "installedBy": "22b312e1-f863-43t7-8c59-5n2f9ll0d09x", + "createdAt": "2024-10-25T17:51:51.222052Z", + "updatedAt": "2025-04-22T16:24:58.768939Z", + "status": "Active" + } + ] + } + } + } + } + }, + "put": { + "tags": [ + "SSL Certificates" + ], + "summary": "Install or renew SSL certificate", + "description": "Installs or renews an SSL certificate using `application/json` or `multipart/form-data` content types.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| CDN API | Certificate management | **Update certificate** |\r\n| CDN API | Certificate management | **View certificate** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "parameters": [ + { + "$ref": "#/components/parameters/Content-Type" + }, + { + "$ref": "#/components/parameters/Accept" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Request body with SSL certificate information.", + "required": [ + "hosts", + "certificate", + "privateKey" + ], + "properties": { + "hosts": { + "type": "array", + "description": "List of hosts.", + "items": { + "type": "string", + "description": "Host name.", + "example": "mystore.com" + } + }, + "certificate": { + "type": "string", + "description": "Base64 encoded SSL certificate.", + "example": "LS0tLS1CRUd...S0tLS0K" + }, + "privateKey": { + "type": "string", + "description": "Base64 encoded SSL certificate private key.", + "example": "LS0tLS1CRUd...LS0NCg==" + } + } + } + }, + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "Hosts": { + "type": "array", + "description": "List of hosts.", + "items": { + "type": "string", + "description": "Host name.", + "example": "mystore.com" + } + }, + "Certificate": { + "type": "string", + "description": "SSL certificate file path.", + "example": "@\"/path/to/certificate.crt\"" + }, + "PrivateKey": { + "type": "string", + "description": "SSL certificate private key file path.", + "example": "@\"/path/to/private.key\"" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "description": "List of SSL certificates.", + "items": { + "type": "object", + "description": "Information about each SSL certificate.", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the certificate.", + "nullable": false + }, + "account": { + "type": "string", + "description": "Account name associated with the certificate.", + "nullable": false + }, + "host": { + "type": "string", + "description": "Primary host/domain of the certificate.", + "nullable": false + }, + "serialNumber": { + "type": "string", + "description": "Certificate serial number.", + "nullable": false + }, + "subjectDistinguishedName": { + "type": "string", + "description": "Full distinguished name of the subject.", + "nullable": false + }, + "subjectCommonName": { + "type": "string", + "description": "Common name (CN) of the certificate subject.", + "nullable": false + }, + "subjectOrganization": { + "type": "string", + "description": "Organization (O) of the certificate subject.", + "nullable": true + }, + "issuerDistinguishedName": { + "type": "string", + "description": "Full distinguished name of the issuing certificate authority.", + "nullable": false + }, + "issuerCommonName": { + "type": "string", + "description": "Common name (CN) of the certificate issuer.", + "nullable": false + }, + "issuerOrganization": { + "type": "string", + "description": "Organization (O) of the certificate issuer.", + "nullable": false + }, + "installDate": { + "type": "string", + "description": "Timestamp when the certificate was installed in ISO 8601 format.", + "nullable": false + }, + "startDate": { + "type": "string", + "description": "Certificate validity start date in ISO 8601 format.", + "nullable": false + }, + "expiryDate": { + "type": "string", + "description": "Certificate expiry date in ISO 8601 format.", + "nullable": false + }, + "signatureAlgorithm": { + "type": "string", + "description": "Algorithm used to sign the certificate.", + "nullable": false + }, + "x509Version": { + "type": "string", + "description": "X.509 version of the certificate.", + "nullable": false + }, + "installedBy": { + "type": "string", + "description": "ID of the user that installed the certificate.", + "nullable": false + }, + "createdAt": { + "type": "string", + "description": "Creation timestamp of the certificate entry in ISO 8601 format.", + "nullable": false + }, + "updatedAt": { + "type": "string", + "description": "Timestamp of the last certificate update in ISO 8601 format.", + "nullable": false + }, + "status": { + "type": "string", + "description": "Current status of the certificate, which can be one of the following:\n\n- **Active**: Valid and active for the host.\n- **Overwritten**: The certificate for this host has been replaced by another through an external method, such as an API call on the CDN.\n- **Installing**: Certificate installation in progress.\n- **Unknown**: The certificate status couldn't be determined due to internal technical problems with communication, configuration, or monitoring.\n- **Expires soon**: The certificate is close to its expiration date (30 days before or less).\n- **Installation failed**: After the status Installing, the installation can fail, and the user will need to try again later.\n- **Expired**: The expiration date passed.", + "nullable": false, + "enum": [ + "Active", + "Overwritten", + "Installing", + "Unknown", + "Expires soon", + "Installation failed", + "Expired" + ] + } + } + } + }, + "example": [ + { + "id": "8c66122e-85cd-4bff-885d-aa9846e97541", + "account": "myaccountname", + "host": "mystore.com", + "serialNumber": "05C51F848EDBAC18E91D9AE43D8F6728D4F8", + "subjectDistinguishedName": "CN=mystore.com", + "subjectCommonName": "mystore.com", + "subjectOrganization": null, + "issuerDistinguishedName": "CN=R10, O=Let's Encrypt, C=US", + "issuerCommonName": "R10", + "issuerOrganization": "Let's Encrypt", + "installDate": "2025-04-22T16:24:58.768939Z", + "startDate": "2024-08-29T01:43:25Z", + "expiryDate": "2024-11-27T01:43:24Z", + "signatureAlgorithm": "sha256RSA", + "x509Version": "3", + "installedBy": "22b312e1-f863-43t7-8c59-5n2f9ll0d09x", + "createdAt": "2024-10-25T17:51:51.222052Z", + "updatedAt": "2025-04-22T16:24:58.768939Z", + "status": "Installing" + } + ] + } + } + } + } + } + }, + "/api/edge/certificates/{certificateId}": { + "get": { + "tags": [ + "SSL Certificates" + ], + "summary": "Get SSL certificate by ID", + "description": "Retrieves information about a specific SSL certificate.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| CDN API | Certificate management | **View certificate** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "parameters": [ + { + "name": "certificateId", + "in": "path", + "description": "SSL certificate unique identifier.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "8c66122e-85cd-4bff-885d-aa9846e97541" + } + }, + { + "$ref": "#/components/parameters/Content-Type" + }, + { + "$ref": "#/components/parameters/Accept" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Information about an SSL certificate.", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the certificate.", + "nullable": false + }, + "account": { + "type": "string", + "description": "Account name associated with the certificate.", + "nullable": false + }, + "host": { + "type": "string", + "description": "Primary host/domain of the certificate.", + "nullable": false + }, + "serialNumber": { + "type": "string", + "description": "Certificate serial number.", + "nullable": false + }, + "subjectDistinguishedName": { + "type": "string", + "description": "Full distinguished name of the subject.", + "nullable": false + }, + "subjectCommonName": { + "type": "string", + "description": "Common name (CN) of the certificate subject.", + "nullable": false + }, + "subjectOrganization": { + "type": "string", + "description": "Organization (O) of the certificate subject.", + "nullable": true + }, + "issuerDistinguishedName": { + "type": "string", + "description": "Full distinguished name of the issuing certificate authority.", + "nullable": false + }, + "issuerCommonName": { + "type": "string", + "description": "Common name (CN) of the certificate issuer.", + "nullable": false + }, + "issuerOrganization": { + "type": "string", + "description": "Organization (O) of the certificate issuer.", + "nullable": false + }, + "installDate": { + "type": "string", + "description": "Timestamp when the certificate was installed in ISO 8601 format.", + "nullable": false + }, + "startDate": { + "type": "string", + "description": "Certificate validity start date in ISO 8601 format.", + "nullable": false + }, + "expiryDate": { + "type": "string", + "description": "Certificate expiry date in ISO 8601 format.", + "nullable": false + }, + "signatureAlgorithm": { + "type": "string", + "description": "Algorithm used to sign the certificate.", + "nullable": false + }, + "x509Version": { + "type": "string", + "description": "X.509 version of the certificate.", + "nullable": false + }, + "installedBy": { + "type": "string", + "description": "ID of the user that installed the certificate.", + "nullable": false + }, + "createdAt": { + "type": "string", + "description": "Creation timestamp of the certificate entry in ISO 8601 format.", + "nullable": false + }, + "updatedAt": { + "type": "string", + "description": "Timestamp of the last certificate update in ISO 8601 format.", + "nullable": false + }, + "status": { + "type": "string", + "description": "Current status of the certificate, which can be one of the following:\n\n- **Active**: Valid and active for the host.\n- **Overwritten**: The certificate for this host has been replaced by another through an external method, such as an API call on the CDN.\n- **Installing**: Certificate installation in progress.\n- **Unknown**: The certificate status couldn't be determined due to internal technical problems with communication, configuration, or monitoring.\n- **Expires soon**: The certificate is close to its expiration date (30 days before or less).\n- **Installation failed**: After the status Installing, the installation can fail, and the user will need to try again later.\n- **Expired**: The expiration date passed.", + "nullable": false, + "enum": [ + "Active", + "Overwritten", + "Installing", + "Unknown", + "Expires soon", + "Installation failed", + "Expired" + ] + } + } + }, + "example": { + "id": "8c66122e-85cd-4bff-885d-aa9846e97541", + "account": "myaccountname", + "host": "mystore.com", + "serialNumber": "05C51F848EDBAC18E91D9AE43D8F6728D4F8", + "subjectDistinguishedName": "CN=mystore.com", + "subjectCommonName": "mystore.com", + "subjectOrganization": null, + "issuerDistinguishedName": "CN=R10, O=Let's Encrypt, C=US", + "issuerCommonName": "R10", + "issuerOrganization": "Let's Encrypt", + "installDate": "2025-04-22T16:24:58.768939Z", + "startDate": "2024-08-29T01:43:25Z", + "expiryDate": "2024-11-27T01:43:24Z", + "signatureAlgorithm": "sha256RSA", + "x509Version": "3", + "installedBy": "22b312e1-f863-43t7-8c59-5n2f9ll0d09x", + "createdAt": "2024-10-25T17:51:51.222052Z", + "updatedAt": "2025-04-22T16:24:58.768939Z", + "status": "Active" + } + } + } + } + } + } + } + }, + "security": [ + { + "appKey": [], + "appToken": [] + }, + { + "VtexIdclientAutCookie": [] + } + ], + "components": { + "securitySchemes": { + "appKey": { + "type": "apiKey", + "in": "header", + "name": "X-VTEX-API-AppKey", + "description": "Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." + }, + "appToken": { + "type": "apiKey", + "in": "header", + "name": "X-VTEX-API-AppToken", + "description": "Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." + }, + "VtexIdclientAutCookie": { + "type": "apiKey", + "in": "header", + "name": "VtexIdclientAutCookie", + "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." + } + }, + "parameters": { + "Content-Type": { + "name": "Content-Type", + "in": "header", + "description": "Type of the content being sent.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "application/json" + } + }, + "Accept": { + "name": "Accept", + "in": "header", + "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", + "required": true, + "style": "simple", + "schema": { + "type": "string", + "example": "application/json" + } + } + } + }, + "tags": [ + { + "name": "SSL Certificates" + } + ] +} \ No newline at end of file