{ "openapi": "3.0.0", "info": { "title": "B2B Password Migration Protocol", "description": "The B2B Password Migration Protocol is a set of definitions to help you integrate your legacy authentication system with VTEX's B2B user migration flow. This protocol defines the endpoints that your middleware must implement to enable B2B password migration. Your middleware must provide a client registration endpoint and an authentication endpoint that VTEX will call during the migration process.\r\n\r\nTo learn more about B2B password migration, check the [B2B password migration guide](https://developers.vtex.com/docs/guides/b2b-password-migration).\r\n\r\n> ⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to selected accounts.\r\n\r\n## Requirements\r\n\r\n- The middleware endpoint must use a standard subdomain or domain name, not an IP address.\r\n- All endpoints must be served over HTTPS on port 443 with TLS 1.3.\r\n- TLS certificates must be valid and issued by a trusted Certificate Authority (CA).\r\n- Endpoints must respond within 3 seconds (p95≤ 1s, p99 ≤ 2.5s recommended).\r\n- Never log the `Secret`, passwords, or signatures.\r\n- Do not reuse secrets across environments (e.g., staging vs. production).", "version": "1.0" }, "servers": [ { "url": "https://{middlewareEndpoint}", "description": "Middleware endpoint URL.", "variables": { "middlewareEndpoint": { "description": "Your authentication middleware endpoint URL (e.g., auth-middleware.example.com).", "default": "auth-middleware.example.com" } } } ], "paths": { "/register": { "post": { "tags": [ "Client registration" ], "summary": "Register client", "description": "Registers VTEX as a client in your middleware and generates the shared credentials used for HMAC request signing. VTEX calls this endpoint before sending any authentication requests.\r\n\r\nFor more information, see the [B2B password migration guide](https://developers.vtex.com/docs/guides/b2b-password-migration).\r\n\r\nYour middleware must:\r\n1. Generate a unique `ClientId` for the store.\r\n2. Generate a high-entropy `Secret` (recommended: 32+ random bytes / 256-bit, encoded as Base64).\r\n3. Store the mapping between the store name, ClientId, and Secret.\r\n4. Return the generated credentials to VTEX.\r\n\r\n> ℹ️ This request is made from VTEX to your authentication middleware during the initial setup.\r\n\r\n## Security requirements\r\n\r\n- The `Secret` should be a high-entropy value (recommended: 32+ random bytes / 256-bit, encoded as Base64).\r\n- Store the `Secret` securely and treat it as a sensitive credential.\r\n- Never log the `Secret` or expose it in error messages.\r\n- Do not reuse secrets across different environments (staging vs. production).\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "RegisterClient", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "schema": { "type": "string", "default": "application/json; charset=utf-8" } }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "description": "Store information for client registration.", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Store" ], "properties": { "Store": { "type": "string", "description": "Name of the VTEX store registering as a client." } } }, "example": { "Store": "store-name" } } } }, "responses": { "200": { "description": "OK\n\nClient registered successfully and returns the generated credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "Store": { "type": "string", "description": "Echo of the store name from the request." }, "ClientId": { "type": "string", "description": "Generated client identifier. This will be sent in the `X-VTEX-Client-Id` header in subsequent requests." }, "Secret": { "type": "string", "description": "Generated shared secret (Base64-encoded). Used by VTEX to sign requests via HMAC-SHA256." } } }, "example": { "Store": "store-name", "ClientId": "", "Secret": "" } } } }, "400": { "description": "Bad Request\n\nInvalid request format or missing required fields." }, "500": { "description": "Internal Server Error\n\nError generating credentials on the middleware side." } }, "security": [] } }, "/authentication": { "post": { "tags": [ "Authentication flow" ], "summary": "Validate legacy credentials", "description": "Validates a user's legacy credentials against your external authentication system. This endpoint is called by VTEX when a user with the `isLegacyPassword` flag attempts to log in for the first time.\r\n\r\nFor more information, see the [B2B password migration guide](https://developers.vtex.com/docs/guides/b2b-password-migration).\r\n\r\n⚠️ The request to your middleware will always be made from one of the VTEX IPs listed at [http://ips.vtex.com](http://ips.vtex.com). Although VTEX cannot enforce this, we strongly recommend that your middleware checks the IP origin. If the IP is not from VTEX, your middleware should not respond.\r\n\r\n> ℹ️ This request is made from VTEX to your authentication middleware.\r\n\r\n## Endpoint-specific requirements\r\n\r\n- The endpoint path must end with `/authentication`.\r\n- Must validate HMAC-SHA256 signatures to authenticate requests from VTEX.\r\n- Must check that requests originate from VTEX IP addresses.\r\n\r\n## Middleware verification steps\r\n\r\nYour middleware must perform the following steps in order:\r\n\r\n1. Validate that all required headers are present.\r\n2. Validate timestamp within ±300 seconds (recommended).\r\n3. Validate that the nonce has not been seen before for this `ClientId` within the clock skew window.\r\n4. Reconstruct the canonical string from the incoming request.\r\n5. Compute the expected HMAC-SHA256 signature and compare using constant-time comparison.\r\n6. Only then proceed to validate credentials against the legacy system.\r\n\r\n## HMAC signature validation\r\n\r\nVTEX and your middleware must sign the exact same canonical string. Your middleware must reconstruct it from the incoming request.\r\n\r\n**Canonical string format (with `\\n` separators, UTF-8 encoded):**\r\n\r\n```\r\n{HTTP_METHOD}\\n\r\n{PATH}\\n\r\n{X-VTEX-Client-Id}\\n\r\n{X-VTEX-Timestamp}\\n\r\n{X-VTEX-Nonce}\\n\r\n{SHA256_OF_BODY}\r\n```\r\n\r\nWhere:\r\n- `HTTP_METHOD` is uppercase (e.g., `POST`).\r\n- `PATH` is `/authentication` and any provided query strings (no scheme or host).\r\n- `SHA256_OF_BODY` is the base64-encoded SHA-256 digest of the raw request body bytes. Do not parse or re-serialize the JSON.\r\n\r\n**Signature computation:**\r\n\r\n```\r\nsignature = HMAC-SHA256(UTF8(canonicalString), secret)\r\n```\r\n\r\n**Authorization header format:**\r\n\r\n```\r\nAuthorization: HMAC-SHA256 SignedHeaders=X-VTEX-Client-Id;X-VTEX-Timestamp;X-VTEX-Nonce;X-VTEX-Content-SHA256&Signature={{signature}}\r\n```\r\n\r\n## Response requirements\r\n\r\nYour middleware must return **only** the following HTTP status codes:\r\n\r\n- `200 OK`: Credentials are valid; user is authorized.\r\n- `401 Unauthorized`: Credentials are invalid (user not found or wrong password).\r\n- `403 Forbidden`: Request is not authenticated (invalid or missing HMAC).\r\n\r\nAny other HTTP status code is treated by VTEX as a technical error.\r\n\r\n⚠️ **Important for security:** \"User not found\" and \"wrong password\" scenarios must both return `401`, indistinguishably. This prevents user enumeration. Don't include response body content that reveals credential validity, user existence, or internal errors. VTEX ignores response bodies entirely.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "ValidateLegacyCredentials", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "schema": { "type": "string", "default": "application/json; charset=utf-8" } }, { "$ref": "#/components/parameters/Accept" }, { "name": "X-VTEX-Client-Id", "in": "header", "description": "Client identifier agreed upon during registration.", "required": true, "schema": { "type": "string", "example": "vtex-b2b-store" } }, { "name": "X-VTEX-Timestamp", "in": "header", "description": "Request timestamp in RFC 1123 format. Must be within an acceptable clock skew window (recommended: ±300 seconds).", "required": true, "schema": { "type": "string", "example": "Tue, 31 Mar 2026 16:11:59 GMT" } }, { "name": "X-VTEX-Nonce", "in": "header", "description": "Unique random string for this request. Must be unique per client within the clock skew window. Your middleware must enforce nonce uniqueness to prevent replay attacks.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "X-VTEX-Content-SHA256", "in": "header", "description": "Base64-encoded SHA-256 hash of the request body.", "required": true, "schema": { "type": "string", "example": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=" } }, { "name": "Authorization", "in": "header", "description": "HMAC-SHA256 signature of the canonical string. Format: `HMAC-SHA256 SignedHeaders=X-VTEX-Client-Id;X-VTEX-Timestamp;X-VTEX-Nonce;X-VTEX-Content-SHA256&Signature={{signature}}`", "required": true, "schema": { "type": "string", "example": "HMAC-SHA256 SignedHeaders=X-VTEX-Client-Id;X-VTEX-Timestamp;X-VTEX-Nonce;X-VTEX-Content-SHA256&Signature=mK8C3gF9xQ7vN2pL5wR8tY6uI4oP1aS3dF7gH9jK2lZ=" } } ], "requestBody": { "description": "Legacy user credentials to validate.", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string", "description": "The user's username or login identifier from the legacy system." }, "password": { "type": "string", "description": "The user's password in plain text. Your middleware is responsible for secure handling and validation." } } }, "example": { "username": "john.doe", "password": "MySecureP@ssw0rd" } } } }, "responses": { "200": { "description": "OK\n\nCredentials are valid and user is authorized." }, "401": { "description": "Unauthorized\n\nCredentials are invalid as user not found or wrong password." }, "403": { "description": "Forbidden\n\nRequest is not authenticated due to invalid or missing HMAC." } }, "security": [] } } }, "components": { "parameters": { "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", "default": "application/json" } } }, "securitySchemes": {} }, "tags": [ { "name": "Client registration" }, { "name": "Authentication flow" } ] }