From f0108f2099c4f394399306de9d6e84cd1c061c33 Mon Sep 17 00:00:00 2001 From: julia-rabello <77292838+julia-rabello@users.noreply.github.com> Date: Wed, 2 Jul 2025 16:04:35 -0300 Subject: [PATCH 1/4] new(guide): punchout login integration --- .../punchout-login-integration.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 docs/localization/punchout-login-integration.md diff --git a/docs/localization/punchout-login-integration.md b/docs/localization/punchout-login-integration.md new file mode 100644 index 0000000000..f1598fd05b --- /dev/null +++ b/docs/localization/punchout-login-integration.md @@ -0,0 +1,97 @@ +--- +title: "Punchout login integration" +slug: "punchout-login-integration" +excerpt: "Learn how to securely integrate external procurement systems with VTEX stores using Punchout login flows and one-time tokens." +hidden: false +createdAt: "2025-07-02T00:00:00.000Z" +updatedAt: "2025-07-02T00:00:00.000Z" +--- + +Punchout login integration enables external procurement systems to authenticate users into a VTEX store without requiring manual credential input. This guide explains how to implement the [Punchout](https://developers.vtex.com/docs/guides/punchout) login flow using one-time tokens (OTT) for secure, session-based authentication. + +The flow supports two integration types: + +* **[VTEX user flow](#vtex-user-flow):** For procurement users who exist on the VTEX platform. In this flow, the username and password are sent as part of the request body, and VTEX is responsible for authorization. + +* **[Pre-authenticated user flow](#pre-authenticated-user-flow):** For procurement users who do not exist in VTEX. In these cases, VTEX trusts the integrator to authorize these users, and receive their username for login. + +## How it works + +The authentication flow starts with a request to a Punchout endpoint and ends with the user's browser being redirected to a store page in a logged-in state. + +The authentication process creates a one-time token (OTT) and returns a URL to be accessed by the procurement system. This URL starts a user session in the VTEX store. + +Example flow: + +1. Request (VTEX user flow): + + `https://host.com/api/authenticator/punchout/start?returnURL=/checkout` + +1. Final redirect (logged-in session): + + `https://host.com/checkout` + +Each flow returns a URL with a short-lived token that must be accessed within 5 minutes and can only be used once. + +## VTEX user flow + +This flow validates the credentials of an existing VTEX user. It requires the user’s email and password. If the validation is positive, the response provides a URL that can be accessed directly via web browsers, initiating a session in the selected host. + +>ℹ️ Find more details about each field in `POST` [Start VTEX user punchout flow](https://developers.vtex.com/docs/api-reference/api-reference/punchout-api#post-/api/authenticator/punchout/start). + +### Request example + +```json +curl -X POST "https://store.myvtex.com/api/authenticator/punchout/start?returnURL=/checkout" \ + -H "Content-Type: application/json" \ + -d '{ + "username": "user@example.com", + "password": "vtex_user_password" + }' +``` + +### Response body example + +```json +{ + "url": "https://apiexamples.com/punchout/redirect/OTT123" +} +``` + +## Pre-authenticated user flow + +This flow is used when the procurement user doesn’t exist in VTEX. In this case, no password is required. An authenticated integration, using a valid API key / API Token pair associated with a role that has the `CanPunchout` permission, generates an OTT on the user’s behalf. Other authentication methods (such as `VtexIdClientAutCookie`) don't work for this endpoint. + +If the validation is positive, the response provides a URL that can be accessed directly via web browsers, initiating a session created with the username provided in the request body. + +>ℹ️ Find more details about each field in `POST` [Start pre-authenticated user punchout flow](https://developers.vtex.com/docs/api-reference/punchout-api#post-/api/authenticator/punchout/authenticated/start). + +### Request example + +```json +curl -X POST "https://store.myvtex.com/api/authenticator/punchout/authenticated/start?returnURL=/checkout" \ + -H "Content-Type: application/json" \ + -H "X-VTEX-API-AppKey: your-app-key" \ + -H "X-VTEX-API-AppToken: your-app-token" \ + -d '{ + "username": "buyer@company.com" + }' +``` + +### Response body example + +```json +{ + "url": "https://apiexamples.com/punchout/redirect/OTT123" +} +``` + +## Security mechanisms + +Punchout login flows use the following security mechanisms to protect credentials and redirect behavior: + +* **One-Time Tokens (OTT)**: Tokens expire after 5 minutes and can be used only once. + +* **Secure credential handling**: Credentials are validated directly against the VTEX user database (VTEX user flow) or the request is made with secure API credentials (pre-authenticated flow). + +* **Redirect protection**: The `returnURL` is validated against authorized hosts to avoid open redirects. From 7dcabbac58851c91d0ef7665047ba0af6829d373 Mon Sep 17 00:00:00 2001 From: "George B. de Lima" <106821144+GeorgeLimaDev@users.noreply.github.com> Date: Thu, 17 Jul 2025 10:22:47 -0300 Subject: [PATCH 2/4] New translations punchout-login-integration.md (English, United States) --- .../punchout-login-integration.md_en | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 docs/localization/punchout-login-integration.md_en diff --git a/docs/localization/punchout-login-integration.md_en b/docs/localization/punchout-login-integration.md_en new file mode 100644 index 0000000000..d3fd2a3e93 --- /dev/null +++ b/docs/localization/punchout-login-integration.md_en @@ -0,0 +1,97 @@ +--- +title: "Punchout login integration" +slug: "punchout-login-integration" +excerpt: "Learn how to securely integrate external procurement systems with VTEX stores using Punchout login flows and one-time tokens." +hidden: false +createdAt: "2025-07-02T00:00:00.000Z" +updatedAt: "2025-07-02T00:00:00.000Z" +--- + +The Punchout login integration enables external procurement systems to authenticate users into a VTEX store without requiring manual credential input. This guide explains how to implement the [Punchout](https://developers.vtex.com/docs/guides/punchout) login flow using one-time tokens (OTT) for secure, session-based authentication. + +The flow supports two integration types: + +* **[VTEX user flow](#vtex-user-flow):** For procurement users who exist on the VTEX platform. In this flow, the username and password are sent as part of the request body, and VTEX authorizes them. + +* **[Pre-authenticated user flow](#pre-authenticated-user-flow):** For procurement users who don't exist on VTEX. In these cases, VTEX trusts the integrator to authorize these users and receive their username for login. + +## How it works + +The authentication flow starts with a request to a Punchout endpoint and ends with the user's browser being redirected to a store page in a logged-in state. + +The authentication process creates a one-time token (OTT) and returns a URL to be accessed by the procurement system. This URL starts a user session in the VTEX store. + +Example flow: + +1. Request (VTEX user flow): + +`https://host.com/api/authenticator/punchout/start?returnURL=/checkout` + +1. Final redirect (logged-in session): + +`https://host.com/checkout` + +Each flow returns a URL with a short-lived token that must be accessed within 5 minutes and can only be used once. + +## VTEX user flow + +This flow validates the credentials of an existing VTEX user. It requires the user’s email and password. If the validation is positive, the response provides a URL that can be accessed directly via web browsers, initiating a session in the selected host. + +>ℹ️ Find more details about each field in `POST` in [Start VTEX user punchout flow](https://developers.vtex.com/docs/api-reference/api-reference/punchout-api#post-/api/authenticator/punchout/start). + +### Request example + +```json +curl -X POST "https://store.myvtex.com/api/authenticator/punchout/start?returnURL=/checkout" \ + -H "Content-Type: application/json" \ + -d '{ + "username": "user@example.com", + "password": "vtex_user_password" + }' +``` + +### Response body example + +```json +{ + "url": "https://apiexamples.com/punchout/redirect/OTT123" +} +``` + +## Pre-authenticated user flow + +This flow is used when the procurement user doesn’t exist on VTEX. In this case, a password isn't required. An authenticated integration, using a valid API key/API token pair associated with a role that has the `CanPunchout` permission, generates an OTT on behalf of the user. Other authentication methods (such as `VtexIdClientAutCookie`) don't work for this endpoint. + +If the validation is positive, the response provides a URL that can be accessed directly via web browsers, initiating a session created with the username provided in the request body. + +>ℹ️ Find more details about each field in `POST` in [Start pre-authenticated user punchout flow](https://developers.vtex.com/docs/api-reference/punchout-api#post-/api/authenticator/punchout/authenticated/start). + +### Request example + +```json +curl -X POST "https://store.myvtex.com/api/authenticator/punchout/authenticated/start?returnURL=/checkout" \ + -H "Content-Type: application/json" \ + -H "X-VTEX-API-AppKey: your-app-key" \ + -H "X-VTEX-API-AppToken: your-app-token" \ + -d '{ + "username": "buyer@company.com" + }' +``` + +### Response body example + +```json +{ + "url": "https://apiexamples.com/punchout/redirect/OTT123" +} +``` + +## Security mechanisms + +Punchout login flows use the following security mechanisms to protect credentials and redirect behavior: + +* **One-Time Tokens (OTT)**: Tokens expire after 5 minutes and can be used only once. + +* **Secure credential handling**: Credentials are validated directly against the VTEX user database (VTEX user flow) or the request is made with secure API credentials (pre-authenticated flow). + +* **Redirect protection**: The `returnURL` is validated against authorized hosts to avoid open redirects. From ce2fd1753c05e02dfb7b6eae54640dfbe61d8622 Mon Sep 17 00:00:00 2001 From: sheilagomes Date: Thu, 17 Jul 2025 10:24:27 -0300 Subject: [PATCH 3/4] Fix formatting --- .../punchout-login-integration.md | 16 +-- .../punchout-login-integration.md_en | 97 ------------------- 2 files changed, 8 insertions(+), 105 deletions(-) delete mode 100644 docs/localization/punchout-login-integration.md_en diff --git a/docs/localization/punchout-login-integration.md b/docs/localization/punchout-login-integration.md index f1598fd05b..d3fd2a3e93 100644 --- a/docs/localization/punchout-login-integration.md +++ b/docs/localization/punchout-login-integration.md @@ -7,13 +7,13 @@ createdAt: "2025-07-02T00:00:00.000Z" updatedAt: "2025-07-02T00:00:00.000Z" --- -Punchout login integration enables external procurement systems to authenticate users into a VTEX store without requiring manual credential input. This guide explains how to implement the [Punchout](https://developers.vtex.com/docs/guides/punchout) login flow using one-time tokens (OTT) for secure, session-based authentication. +The Punchout login integration enables external procurement systems to authenticate users into a VTEX store without requiring manual credential input. This guide explains how to implement the [Punchout](https://developers.vtex.com/docs/guides/punchout) login flow using one-time tokens (OTT) for secure, session-based authentication. The flow supports two integration types: -* **[VTEX user flow](#vtex-user-flow):** For procurement users who exist on the VTEX platform. In this flow, the username and password are sent as part of the request body, and VTEX is responsible for authorization. +* **[VTEX user flow](#vtex-user-flow):** For procurement users who exist on the VTEX platform. In this flow, the username and password are sent as part of the request body, and VTEX authorizes them. -* **[Pre-authenticated user flow](#pre-authenticated-user-flow):** For procurement users who do not exist in VTEX. In these cases, VTEX trusts the integrator to authorize these users, and receive their username for login. +* **[Pre-authenticated user flow](#pre-authenticated-user-flow):** For procurement users who don't exist on VTEX. In these cases, VTEX trusts the integrator to authorize these users and receive their username for login. ## How it works @@ -25,11 +25,11 @@ Example flow: 1. Request (VTEX user flow): - `https://host.com/api/authenticator/punchout/start?returnURL=/checkout` +`https://host.com/api/authenticator/punchout/start?returnURL=/checkout` 1. Final redirect (logged-in session): - `https://host.com/checkout` +`https://host.com/checkout` Each flow returns a URL with a short-lived token that must be accessed within 5 minutes and can only be used once. @@ -37,7 +37,7 @@ Each flow returns a URL with a short-lived token that must be accessed within 5 This flow validates the credentials of an existing VTEX user. It requires the user’s email and password. If the validation is positive, the response provides a URL that can be accessed directly via web browsers, initiating a session in the selected host. ->ℹ️ Find more details about each field in `POST` [Start VTEX user punchout flow](https://developers.vtex.com/docs/api-reference/api-reference/punchout-api#post-/api/authenticator/punchout/start). +>ℹ️ Find more details about each field in `POST` in [Start VTEX user punchout flow](https://developers.vtex.com/docs/api-reference/api-reference/punchout-api#post-/api/authenticator/punchout/start). ### Request example @@ -60,11 +60,11 @@ curl -X POST "https://store.myvtex.com/api/authenticator/punchout/start?returnUR ## Pre-authenticated user flow -This flow is used when the procurement user doesn’t exist in VTEX. In this case, no password is required. An authenticated integration, using a valid API key / API Token pair associated with a role that has the `CanPunchout` permission, generates an OTT on the user’s behalf. Other authentication methods (such as `VtexIdClientAutCookie`) don't work for this endpoint. +This flow is used when the procurement user doesn’t exist on VTEX. In this case, a password isn't required. An authenticated integration, using a valid API key/API token pair associated with a role that has the `CanPunchout` permission, generates an OTT on behalf of the user. Other authentication methods (such as `VtexIdClientAutCookie`) don't work for this endpoint. If the validation is positive, the response provides a URL that can be accessed directly via web browsers, initiating a session created with the username provided in the request body. ->ℹ️ Find more details about each field in `POST` [Start pre-authenticated user punchout flow](https://developers.vtex.com/docs/api-reference/punchout-api#post-/api/authenticator/punchout/authenticated/start). +>ℹ️ Find more details about each field in `POST` in [Start pre-authenticated user punchout flow](https://developers.vtex.com/docs/api-reference/punchout-api#post-/api/authenticator/punchout/authenticated/start). ### Request example diff --git a/docs/localization/punchout-login-integration.md_en b/docs/localization/punchout-login-integration.md_en deleted file mode 100644 index d3fd2a3e93..0000000000 --- a/docs/localization/punchout-login-integration.md_en +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "Punchout login integration" -slug: "punchout-login-integration" -excerpt: "Learn how to securely integrate external procurement systems with VTEX stores using Punchout login flows and one-time tokens." -hidden: false -createdAt: "2025-07-02T00:00:00.000Z" -updatedAt: "2025-07-02T00:00:00.000Z" ---- - -The Punchout login integration enables external procurement systems to authenticate users into a VTEX store without requiring manual credential input. This guide explains how to implement the [Punchout](https://developers.vtex.com/docs/guides/punchout) login flow using one-time tokens (OTT) for secure, session-based authentication. - -The flow supports two integration types: - -* **[VTEX user flow](#vtex-user-flow):** For procurement users who exist on the VTEX platform. In this flow, the username and password are sent as part of the request body, and VTEX authorizes them. - -* **[Pre-authenticated user flow](#pre-authenticated-user-flow):** For procurement users who don't exist on VTEX. In these cases, VTEX trusts the integrator to authorize these users and receive their username for login. - -## How it works - -The authentication flow starts with a request to a Punchout endpoint and ends with the user's browser being redirected to a store page in a logged-in state. - -The authentication process creates a one-time token (OTT) and returns a URL to be accessed by the procurement system. This URL starts a user session in the VTEX store. - -Example flow: - -1. Request (VTEX user flow): - -`https://host.com/api/authenticator/punchout/start?returnURL=/checkout` - -1. Final redirect (logged-in session): - -`https://host.com/checkout` - -Each flow returns a URL with a short-lived token that must be accessed within 5 minutes and can only be used once. - -## VTEX user flow - -This flow validates the credentials of an existing VTEX user. It requires the user’s email and password. If the validation is positive, the response provides a URL that can be accessed directly via web browsers, initiating a session in the selected host. - ->ℹ️ Find more details about each field in `POST` in [Start VTEX user punchout flow](https://developers.vtex.com/docs/api-reference/api-reference/punchout-api#post-/api/authenticator/punchout/start). - -### Request example - -```json -curl -X POST "https://store.myvtex.com/api/authenticator/punchout/start?returnURL=/checkout" \ - -H "Content-Type: application/json" \ - -d '{ - "username": "user@example.com", - "password": "vtex_user_password" - }' -``` - -### Response body example - -```json -{ - "url": "https://apiexamples.com/punchout/redirect/OTT123" -} -``` - -## Pre-authenticated user flow - -This flow is used when the procurement user doesn’t exist on VTEX. In this case, a password isn't required. An authenticated integration, using a valid API key/API token pair associated with a role that has the `CanPunchout` permission, generates an OTT on behalf of the user. Other authentication methods (such as `VtexIdClientAutCookie`) don't work for this endpoint. - -If the validation is positive, the response provides a URL that can be accessed directly via web browsers, initiating a session created with the username provided in the request body. - ->ℹ️ Find more details about each field in `POST` in [Start pre-authenticated user punchout flow](https://developers.vtex.com/docs/api-reference/punchout-api#post-/api/authenticator/punchout/authenticated/start). - -### Request example - -```json -curl -X POST "https://store.myvtex.com/api/authenticator/punchout/authenticated/start?returnURL=/checkout" \ - -H "Content-Type: application/json" \ - -H "X-VTEX-API-AppKey: your-app-key" \ - -H "X-VTEX-API-AppToken: your-app-token" \ - -d '{ - "username": "buyer@company.com" - }' -``` - -### Response body example - -```json -{ - "url": "https://apiexamples.com/punchout/redirect/OTT123" -} -``` - -## Security mechanisms - -Punchout login flows use the following security mechanisms to protect credentials and redirect behavior: - -* **One-Time Tokens (OTT)**: Tokens expire after 5 minutes and can be used only once. - -* **Secure credential handling**: Credentials are validated directly against the VTEX user database (VTEX user flow) or the request is made with secure API credentials (pre-authenticated flow). - -* **Redirect protection**: The `returnURL` is validated against authorized hosts to avoid open redirects. From 1d4a2a246186ce0a29326bbf6517021826fd8de2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BAlia=20Rabello?= <77292838+julia-rabello@users.noreply.github.com> Date: Mon, 21 Jul 2025 09:25:36 -0300 Subject: [PATCH 4/4] fix spacing --- docs/localization/punchout-login-integration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/localization/punchout-login-integration.md b/docs/localization/punchout-login-integration.md index d3fd2a3e93..978b8cb830 100644 --- a/docs/localization/punchout-login-integration.md +++ b/docs/localization/punchout-login-integration.md @@ -25,11 +25,11 @@ Example flow: 1. Request (VTEX user flow): -`https://host.com/api/authenticator/punchout/start?returnURL=/checkout` + `https://host.com/api/authenticator/punchout/start?returnURL=/checkout` 1. Final redirect (logged-in session): -`https://host.com/checkout` + `https://host.com/checkout` Each flow returns a URL with a short-lived token that must be accessed within 5 minutes and can only be used once.