Learn how to securely rotate VTEX API tokens to minimize security risks and ensure uninterrupted service.
The older API tokens are, the higher the risk of exposure and potential damage to your operations. To minimize vulnerabilities and ensure store security, we strongly recommend renewing tokens regularly, ideally before any renewal alert in the API keys dashboard.
This guide explains how to renew VTEX API tokens using the VTEX ID API. Alternatively, you can rotate tokens using the API keys Admin page. Learn more at Renewing API tokens.
The VTEX renewal process allows you to generate a new token while the old one remains active, ensuring uninterrupted service during the transition.
VTEX recommends renewing tokens every 90 or 180 days, based on the policies of your organization. Tokens don't expire automatically, so regular rotation is a proactive security best practice.
Token rotation process
The API-based token rotation process involves two steps, as illustrated in the diagram below:
-
The system initiates the token renewal by calling the
PATCHInitiate token renewal endpoint. The API responds with a new token while keeping the old one active. -
After updating all systems to use the new token, the system calls the
PATCHComplete token renewal endpoint to deactivate the old token and complete the rotation.
Required permission
To ensure security when renewing keys, these endpoints require authorization. You must use a valid API key (not the one being renewed) with access to the following License Manager resource:
| Product | Category | Resource |
|---|---|---|
| License Manager | API Key Management | Renew API Token |
Step 1 - Initiate token renewal
Use the PATCH Initiate token renewal endpoint to start the renewal process. This generates a new API token without deactivating the current one, allowing both to be used simultaneously during the transition period.
Request example
_10curl -X PATCH "https://apiexamples.vtexcommercestable.com.br/api/vtexid/apikey/{apiKey}/apitoken/renew" \_10 -H "Content-Type: application/json" \_10 -H "X-VTEX-API-AppKey: {apiKey}" \_10 -H "X-VTEX-API-AppToken: {apiToken}" \
Response example
_10{_10 "id": "1f6c17e5-06f9-44a9-a459-b3686e03fa9d",_10 "keyName": "my-api-key",_10 "creationDateToken": "2025-02-18T12:00:00Z",_10 "creationDateNewToken": "2025-02-25T12:00:00Z",_10 "expirationPeriod": 30,_10 "newToken": "abc123xyz789"_10}
The response includes the new token (newToken), which is valid but not yet exclusive. You can now update your systems to use the new token.
Step 2 - Complete token renewal
After you’ve updated all systems to use the new token, call the PATCH Complete token renewal endpoint to complete the process. This step deactivates the old token, ensuring that only the new one remains valid.
Before completing the renewal, make sure that no integrations are still using the old token. This action is can't be undone.
Request example
_10curl -X PATCH "https://apiexamples.vtexcommercestable.com.br/api/vtexid/apikey/my-api-key/apitoken/finish-renewal" \_10 -H "Content-Type: application/json" \_10 -H "X-VTEX-API-AppKey: {apiKey}" \_10 -H "X-VTEX-API-AppToken: {apiToken}"
Response example
_10{_10 "id": "1f6c17e5-06f9-44a9-a459-b3686e03fa9d",_10 "creationDateToken": "2025-02-18T15:30:00Z",_10 "creationDateNewToken": null_10}
A null value in creationDateNewToken confirms that the old token is now deactivated and the rotation is complete.
Post-rotation checklist
After completing the token rotation, make sure to follow the steps below to avoid disruptions and maintain security across all systems:
- Update all environments and tools with the new token.
- Remove the old token from vaults or environment variables.
- Monitor logs for failed authentication attempts.
- Inform affected teams or services about the token change.