| name | vtex-login-headless |
| description | Diagnose and fix headless login issues on VTEX storefronts — covering authorized domain setup and simulating an authenticated session by copying VtexIdclientAutCookie cookies. |
What is VTEX Headless Login
Headless login on VTEX refers to authenticating users outside the VTEX Admin panel — in custom storefronts, external applications, or development environments that consume VTEX APIs with an authenticated session.
Domain restriction
Headless login only works for domains explicitly authorized in the VTEX account settings.
How to authorize a domain
In the VTEX Admin panel, navigate to:
Account Settings → Account → Stores → (select store) → Edit → Add Host
Add the domain (e.g. my-store.com, localhost:3000) to the list of allowed hosts. Without this entry, VTEX will block all headless authentication attempts from that origin.
Simulating an authenticated session (for testing)
When it is not practical to run a full login flow in a test environment, you can copy authentication cookies from an already-authenticated session.
Steps
- Open an authorized domain in the browser and log in normally.
- Open DevTools and go to the Application → Cookies tab.
- Find all cookies whose name starts with:
VtexIdclientAutCookie
- Copy those cookie values.
- In the target environment, inject the same cookies (via DevTools, a cookie-manager extension, or programmatically via
document.cookie).
Cookies to look for
| Name | Description |
|---|
VtexIdclientAutCookie | Main session authentication cookie |
VtexIdclientAutCookie_<accountName> | Per-account variant (present in multi-store setups) |
Note: these cookies expire. If the authenticated state does not persist, check whether the cookies are still valid at the source.
Quick diagnostics
| Symptom | Likely cause |
|---|
| Login keeps redirecting in a loop | Domain is not in the authorized hosts list |
| Copied cookie does not maintain session | Cookie is expired, or the destination domain is not authorized |
API returns 401 even with cookie present | Account name in the cookie does not match the environment |
