{ "openapi": "3.0.0", "info": { "title": "VTEX ID", "description": "VTEX ID API provides endpoints to manage user authentication in your VTEX store. Check the [Authentication](https://developers.vtex.com/docs/guides/authentication) guide for more information.\n\n> ⚠️ This API does not serve stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal). For storefront user registration and B2B password migration configuration, see the [Authenticator API](https://developers.vtex.com/docs/api-reference/authenticator-api) and the [B2B user provisioning](https://developers.vtex.com/docs/guides/b2b-user-provisioning) and [B2B password migration](https://developers.vtex.com/docs/guides/b2b-password-migration) guides.", "version": "1.0" }, "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" } } }, { "url": "https://{accountName}.{environment}.com", "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": [ "myvtex" ], "default": "myvtex" } } }, { "url": "https://{storeDomain}", "description": "Store domain.", "variables": { "storeDomain": { "description": "Store domain.", "default": "apiexamples.com" } } } ], "paths": { "/api/vtexid/pvt/user/info": { "get": { "tags": [ "Storefront users" ], "summary": "Get storefront user by identifier", "description": "Fetches a storefront user by their identifier (username or email). The identifier must be provided as a URL-encoded query parameter.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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| VTEX ID | User Management | **View User** |\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\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>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "user", "in": "query", "description": "URL-encoded storefront user identifier (username or email).", "required": true, "schema": { "type": "string", "example": "john.doe_2025" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK\n\nUser found.", "content": { "application/json": { "schema": { "type": "object", "description": "Storefront user information.", "properties": { "userId": { "type": "string", "description": "Storefront user unique identifier." }, "user": { "type": "string", "description": "Storefront user email." }, "name": { "type": "string", "description": "Storefront user full name." }, "accountId": { "type": "string", "description": "VTEX account ID." }, "accountName": { "type": "string", "description": "VTEX VTEX account name." } } }, "example": { "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "user": "john.doe@example.com", "name": "John Doe", "accountId": "12345", "accountName": "mystore" } } } }, "401": { "description": "Unauthorized\n\nNot authenticated." } }, "security": [ { "appKey": [], "appToken": [] } ] } }, "/api/vtexid/apptoken/login": { "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" } } } ], "post": { "tags": [ "Authentication" ], "summary": "Generate authentication token", "description": "Generate a [token](https://developers.vtex.com/vtex-rest-api/docs/getting-started-authentication#user-token) from a given [app key and app token](https://help.vtex.com/en/tutorial/api-keys--2iffYzlvvz4BDMr6WGUtet) pair. You can use this token to authenticate requests to VTEX APIs by sending it as a header named `VtexIdclientAutCookie`. The token's permissions are the same as [defined to the credential pair](https://help.vtex.com/en/tutorial/api-keys--2iffYzlvvz4BDMr6WGUtet#managing-app-key-permissions).\n\r\n\r> Since you are sending the credentials on the request body, there is no need to send authentication headers. \n\r\n\r> It is also possible to make this request using the `https://api.vtexcommercestable.com.br/api/vtexid/apptoken/login?an={accountName}` route, replacing `{accountName}` with your VTEX account name. This is the only case where you need to use the `an` query parameter.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/an" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/credentials" }, "example": { "appkey": "vtexappkey-example-YSWQFZ", "apptoken": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjA1MTZFN0IwMDNFODMxRTg0QkFDOTg2NzBCNUM2QTRERTlBN0RFNkUiLCJ0eXAiOiJqd3QifQ.eyJzdWIiOiJwZWRyby5jb3N0YUB2dGV4LmNvbS5iciIsImFjY291bnQiOiJhcHBsaWFuY2V0aGVtZSIsImF1ZGllbmNlIjoiYWRtaW4iLCJzZXNzIjoiZjU3YjMyMGItMWE3YS00YzlkLWJkNDMtZTE4NDdhYmE1MTE1IiwiZXhwIjoxNjE2NzY3Mjc4LCJ1c2VySWQiOiJmYjU0MmU1MS01NDg4LTRjMzQtOGQxNy1lZDhmY2Y1OTdhOTQiLCJpYXQiOjE2MwerY2ODA4NzgsImlzcyI6InRva2VuLWVtaXR0ZXIiLCJqdGkiOiJmYTI0YWJiOC03Y2E5LTQ3NjUtYmYzNC1kMmvU5YTgzYjYxZmUifQ.23rn-2dEdAAYXJX2exrxDEdbieyKWsVKABeSUNeFWyhz7xRd7d5EcxwiMLjM3bRaBOKrAA9Op7ocn89c45qQ" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "authStatus": { "type": "string", "description": "Authentication status." }, "token": { "type": "string", "description": "Authentication token." }, "expires": { "type": "integer", "description": "Token expiration Unix timestamp in seconds." } } }, "example": { "authStatus": "Success", "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjFBRjI5MUUwRDY0MERENTlEQTkzRTg0REMxNjQyNjA3ODZEQjY3ODAiLCJ0eXAiOiJqd3QifQ.eyJzdWIiOiJ2dGV4YXBwa2V5LXZ0ZXhoZWxwLVdWQ0FCVCIsImFjY291bnQiOiJwerV4aGVscCIsImF1ZGllbmNlIjoiYWRtaW4iLCJleHAiOjE2Njk3NzA3MzcsInVzZXJJZCI6IjM5MjNhMmUy5khmMTctNGNiYy04YzU3LWQ3OGFkNmUxYTU2NiIsImlhdCI6MTY2OTc0OTEzNywiaXNzIjoidG9rZW4tZW1HgoRlciIsImp0aSI6IjNiNjAxODA2LTExMzEtNDcwYS05MWJjLTVhM2JhOThiYWQyNiJ9.Q7N8MFa1FMJsQUpxBY29oije4aa-Jf29wgLFLl6LUY3Wei3MRUVUMRQWkey6Kug8iFPonZ1L-PaFmwfzSz3TCQ", "expires": 1669770737 } } } } } } }, "/api/vtexid/audience/webstore/provider/oauth/exchange": { "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" } } } ], "post": { "tags": [ "Authentication" ], "summary": "Exchange OAuth access token for VTEX credential", "description": "If your store uses a headless frontend, you can authenticate users via OAuth and use this endpoint to exchange the OAuth access token for a VTEX authentication token. This VTEX token can be used to authenticate your frontend requests to VTEX APIs.\n\r\n\rLearn more about how to implement [headless authentication](https://developers.vtex.com/docs/guides/headless-authentication) in your store.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "providerId", "accessToken" ], "properties": { "providerId": { "type": "string", "description": "Name of the [OAuth provider](https://developers.vtex.com/docs/guides/login-integration-guide-webstore-oauth2) set up in your Admin panel." }, "accessToken": { "type": "string", "description": "Access token obtained from your frontend via OAuth integration corresponding with the indicated `providerId`." }, "duration": { "type": "integer", "description": "Duration of the token that will be returned, in minutes. The maximum value is `120`. The default is `60` when the duration isn't defined.", "default": 60 } } }, "example": { "providerId": "custom-oauth-provider", "accessToken": "dsfDShdgfhDFI1NiIsIrtyZCI6IjFBRjI5MUUwRDY0MERENTlEQTkzRTg0REMxNjQyNjA3ODZEQjY3ODAiLCJ0eXAiOiJqd3QifQ.eyJzdWIiOiJ2dGV4YXBwa2V5LXZ0ZXhoZWxwLVdWQ0FCVCIsImFjY291bdg465DATU4GVscCIsImF1MBllbmNlIjoiYWRtaW4iLCJleHAiOjE2Njk3NzA3MzcsInVzZXJJZCI6IjM5MjNhMmUy5khmMTctNGNiYy04YzU3LWQ3OGFkNmUxYTU2NiIsImlhdCI6MTY2OTc0OTEzNywiaXNzIjoidG9rZW4tZW1HgoRlciIsImp0aSI6IjNiNjAxODA2LTExMzEtNDcwYS05MWJjLTVhM2JhOThiYWQyNiJ9.Q7N8MFa1FMJsQUpxBY29oije4aa-654fgjLFLl6LUY3Wei3MRUVUMRQWkey6Kug8iFPonZ1L-PaFmwfzSz3TCQ", "duration": 90 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "authToken": { "type": "string", "description": "Authentication token. Use this token to authenticate your requests to VTEX APIs." } } }, "example": { "authToken": "eyJhbGciOiJFUzI1NiIsIrtyZCI6IjFBRjI5MUUwRDY0MERENTlEQTkzRTg0REMxNjQyNjA3ODZEQjY3ODAiLCJ0eXAiOiJqd3QifQ.eyJzdWIiOiJ2dGV4YXBwa2V5LXZ0ZXhoZWxwLVdWQ0FCVCIsImFjY291bnQiOiJwerV4aGVscCIsImF1MBllbmNlIjoiYWRtaW4iLCJleHAiOjE2Njk3NzA3MzcsInVzZXJJZCI6IjM5MjNhMmUy5khmMTctNGNiYy04YzU3LWQ3OGFkNmUxYTU2NiIsImlhdCI6MTY2OTc0OTEzNywiaXNzIjoidG9rZW4tZW1HgoRlciIsImp0aSI6IjNiNjAxODA2LTExMzEtNDcwYS05MWJjLTVhM2JhOThiYWQyNiJ9.Q7N8MFa1FMJsQUpxBY29oije4aa-Jf463lwgLFLl6LUY3Wei3MRUVUMRQWkey6Kug8iFPonZ1L-PaFmwfzSz3TCQ" } } } } } } }, "/api/vtexid/credential/validate": { "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" } } } ], "post": { "tags": [ "Authentication" ], "summary": "Check authenticated user", "description": "Retrieves information about the user who is currently authenticated in your store, given an user token. If the user is not authenticated, the response for this API will be `401 (Unauthorized)`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/an" }, { "$ref": "#/components/parameters/environment" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Request body object.", "required": [ "token" ], "properties": { "token": { "description": "Value of the `VtexIdclientAutCookie`, [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.", "type": "string" } } }, "example": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "authStatus": { "type": "string", "description": "Authentication status." }, "id": { "type": "string", "description": "Unique identifier of the user within VTEX services." }, "user": { "type": "string", "description": "User email." }, "account": { "type": "string", "description": "VTEX account name." }, "audience": { "type": "string", "description": "Type of user." }, "tokenType": { "type": "string", "description": "Type of token." } } }, "example": { "authStatus": "Success", "id": "1f6c17e5-06f9-44a9-a459-b3686e03fa9d", "user": "john@mail.com", "account": "apiexamples", "audience": "admin", "tokenType": "user" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "authStatus": { "type": "string", "description": "Authentication status." } } }, "example": { "authStatus": "WrongCredentials" } } } } }, "deprecated": false } }, "/api/vtexid/pub/providers/setup/password/webstore/password": { "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" } } } ], "post": { "tags": [ "Authentication" ], "summary": "Enable or disable repeated passwords", "description": "Defines if user passwords can be repeated in your store. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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| VTEX ID | Identity Providers | **Write Identity Providers** |\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\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>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/accountName" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "isActive": { "type": "boolean", "description": "Defines if password access is active (`true`) or not (`false`)." }, "allowRepeated": { "type": "boolean", "description": "Defines if passwords can be repeated (`true`) or not (`false`)." } } }, "example": { "isActive": true, "allowRepeated": false } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/vtexid/password/expire": { "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" } } } ], "post": { "tags": [ "Authentication" ], "summary": "Expire user password", "description": "Expires an user's password in your store.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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| VTEX ID | User Management | **Expire User Password** |\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\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>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "name": "email", "in": "query", "description": "User email.", "required": true, "schema": { "type": "string", "example": "email@email.com" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/vtexid/apikey/{apiKey}/apitoken/renew": { "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" } } } ], "patch": { "tags": [ "Token renewal" ], "summary": "Initiate token renewal", "description": "Starts the API token renewal process by generating a new token while keeping the current token active. This ensures a smooth transition without service disruption.\r\n\r\nThe previous token and the new token are both valid until the renewal process is completed by making a request to `PATCH` [Complete token renewal](https://developers.vtex.com/docs/api-reference/vtex-id-api#patch-/api/vtexid/apikey/-apiKey-/apitoken/finish-renewal).\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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| License Manager | API Key Management | **Renew API Token** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** |\r\n| --------------- | ----------------- |\r\n| User Administrator - RESTRICTED | **Renew API Token** |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).", "parameters": [ { "$ref": "#/components/parameters/apiKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the API token." }, "keyName": { "type": "string", "description": "Name assigned to the API key." }, "creationDateToken": { "type": "string", "description": "ISO 8601 timestamp indicating when the current token was created." }, "creationDateNewToken": { "type": "string", "description": "ISO 8601 timestamp indicating when the new token was generated." }, "expirationPeriod": { "type": "number", "description": "Number of days the token remains valid before expiration." }, "newToken": { "type": "string", "description": "New API token value." } } }, "example": { "id": "1f6c17e5-06f9-44a9-a459-b3686e03fa9d", "keyName": "my-api-key", "creationDateToken": "2025-02-18T12:00:00Z", "creationDateNewToken": "2025-02-25T12:00:00Z", "expirationPeriod": 30, "newToken": "abc123xyz789" } } } }, "400": { "description": "Bad Request\n\nInvalid API key or API key not owned by tenant." }, "409": { "description": "Conflict\n\nAlready has a renewed token pending." }, "500": { "description": "Internal Server Error\n\nUnknown server error." } } } }, "/api/vtexid/apikey/{apiKey}/apitoken/finish-renewal": { "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" } } } ], "patch": { "tags": [ "Token renewal" ], "summary": "Complete token renewal", "description": "Finalizes the API token renewal process, deactivating the old token. After this step, the old token can no longer be used, ensuring security by enforcing a controlled rotation.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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| License Manager | API Key Management | **Renew API Token** |\r\n\r\n You can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** |\r\n| --------------- | ----------------- |\r\n| User Administrator - RESTRICTED | **Renew API Token** |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).", "parameters": [ { "$ref": "#/components/parameters/apiKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the API token." }, "creationDateToken": { "type": "string", "description": "ISO 8601 timestamp indicating when the current token was created." }, "creationDateNewToken": { "type": "string", "nullable": true, "description": "Creation date of the new token. Always `null` after the token creation process is completed." } } }, "example": { "id": "1f6c17e5-06f9-44a9-a459-b3686e03fa9d", "creationDateToken": "2025-02-18T15:30:00Z", "creationDateNewToken": null } } } }, "400": { "description": "Bad Request\n\nInvalid API key or API key not owned by tenant." }, "404": { "description": "Not Found\n\nNo renewed API token was found." }, "500": { "description": "Internal Server Error\n\nUnknown server error." } } } }, "/api/vtexid/pvt/user/id": { "get": { "tags": [ "Authentication" ], "summary": "Get user ID by email", "description": "Retrieves the unique user ID for a given email address.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). However, it does require a valid user token (`VtexIdclientAutCookie`) to be included in the request headers.\r\n\r\nTo learn more about user authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#user-authentication).", "parameters": [ { "name": "usuario", "in": "query", "description": "User email address.", "required": true, "schema": { "type": "string", "description": "URI-encoded user email.", "example": "john%40mail.com" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "description": "User ID.", "nullable": true }, "example": "1f6c17e5-06f9-44a9-a459-b3686e03fa9d" } } }, "401": { "description": "Unauthorized\n\nInvalid or missing VtexIdclientAutCookie." } }, "security": [ { "VtexIdclientAutCookie": [] } ] } }, "/api/vtexid/pub/authentication/start": { "servers": [ { "url": "https://{storeDomain}", "description": "Store domain.", "variables": { "storeDomain": { "description": "Store domain.", "default": "apiexamples.com" } } }, { "url": "https://{accountName}.{environment}.com", "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": [ "myvtex" ], "default": "myvtex" } } } ], "get": { "tags": [ "Refresh token headless" ], "summary": "Start authentication", "description": "Starts the authentication flow for a user in your store. This endpoint returns an authentication token valid for 24 hours.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "scope", "in": "query", "description": "Account name.", "required": true, "schema": { "type": "string", "example": "accountName" } }, { "name": "fingerprint", "in": "query", "description": "Optional device fingerprint for enhanced security. Generated client-side using JavaScript libraries that collect anonymized device and browser parameters to create a unique identifier. When submitted in this request, it must later be provided when making a request to [refresh token](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/vtexid/refreshtoken/webstore).", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "authenticationToken": { "type": "string", "description": "Authentication token provided to the user, valid for 24 hours." }, "oauthProviders": { "type": "array", "description": "List of available OAuth providers.", "items": { "type": "object", "description": "OAuth provider information.", "properties": { "providerName": { "type": "string", "description": "Name of the OAuth provider." }, "className": { "type": "string", "description": "Class name associated with the provider." }, "expectedContext": { "type": "array", "description": "Additional context expected by the provider.", "items": { "type": "string", "description": "Additional context." } } } } }, "showClassicAuthentication": { "type": "boolean", "description": "Indicates whether classic authentication is enabled (`true`) or not (`false`)." }, "showAccessKeyAuthentication": { "type": "boolean", "description": "Indicates whether access key authentication is enabled (`true`) or not (`false`)." }, "showPasskeyAuthentication": { "type": "boolean", "description": "Indicates whether passkey authentication is enabled (`true`) or not (`false`)." }, "authCookie": { "type": "string", "description": "Authentication cookie if available.", "nullable": true }, "isAuthenticated": { "type": "boolean", "description": "Indicates whether the user is authenticated." }, "selectedProvider": { "type": "string", "description": "Currently selected authentication provider, if any.", "nullable": true }, "samlProviders": { "type": "array", "description": "List of available SAML providers.", "items": { "type": "string", "description": "SAML provider." } } } }, "example": { "authenticationToken": "C17BCD635B637E66BF2BBE07CEED0B1B7425387FB8D6E42FE68EBCE7A49193F2", "oauthProviders": [ { "providerName": "Google", "className": "google-plus", "expectedContext": [] }, { "providerName": "Facebook", "className": "facebook", "expectedContext": [] } ], "showClassicAuthentication": true, "showAccessKeyAuthentication": true, "showPasskeyAuthentication": false, "authCookie": null, "isAuthenticated": false, "selectedProvider": null, "samlProviders": [] } } } } } } }, "/api/vtexid/pub/authentication/accesskey/send": { "servers": [ { "url": "https://{storeDomain}", "description": "Store domain.", "variables": { "storeDomain": { "description": "Store domain.", "default": "apiexamples.com" } } }, { "url": "https://{accountName}.{environment}.com", "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": [ "myvtex" ], "default": "myvtex" } } } ], "post": { "tags": [ "Refresh token headless" ], "summary": "Send access key", "description": "Sends an access key to the user's email address, if the response is empty with 200 OK. The access key is used to authenticate the user in your store.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "email", "in": "query", "description": "User email.", "required": true, "schema": { "type": "string", "example": "jane@mail.com" } }, { "name": "_vss", "in": "cookie", "description": "Authentication token obtained in the [Start authentication](https://developers.vtex.com/docs/api-reference/vtex-id-api#get-/api/vtexid/pub/authentication/start) request.", "required": true, "schema": { "type": "string", "example": "C17BCD635B637E66BF2BBE07CEED0B1B7425387FB8D6E42FE68EBCE7A49193F2" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "authStatus": { "type": "string", "description": "Error message, which can be `InvalidEmail` (when the email informed is not valid) or `InvalidToken` (when the token is malformed, expired, or has an invalid signature)." } } }, "example": { "authStatus": "InvalidEmail" } } } } } } }, "/api/vtexid/pub/authentication/accesskey/validate": { "servers": [ { "url": "https://{storeDomain}", "description": "Store domain.", "variables": { "storeDomain": { "description": "Store domain.", "default": "apiexamples.com" } } }, { "url": "https://{accountName}.{environment}.com", "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": [ "myvtex" ], "default": "myvtex" } } } ], "post": { "tags": [ "Refresh token headless" ], "summary": "Validate session", "description": "Validates the user session using the access key sent to the user through the [Send access key](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/vtexid/pub/authentication/accesskey/send) endpoint.\r\n\r\nThe refresh token (`vid_rt`) is returned in the `Set-Cookie` header. This token is required for the [Refresh token](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/vtexid/refreshtoken/webstore) request.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "_vss", "in": "cookie", "description": "Authentication token obtained in the [Start authentication](https://developers.vtex.com/docs/api-reference/vtex-id-api#get-/api/vtexid/pub/authentication/start) request.", "required": true, "schema": { "type": "string", "example": "C17BCD635B637E66BF2BBE07CEED0B1B7425387FB8D6E42FE68EBCE7A49193F2" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "accessKey": { "type": "string", "description": "Access key sent to the user through the [Send access key](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/vtexid/pub/authentication/accesskey/send) endpoint." }, "login": { "type": "string", "description": "User email." } } }, "example": { "accessKey": "123456", "login": "user@example.com" } } } }, "responses": { "200": { "description": "OK", "headers": { "Set-Cookie": { "description": "Refresh token.", "schema": { "type": "string" }, "example": "vid_rt=QiEOQKuzdRjukvSnsn7F8h1wwkrqq8wWlkk7bXA5LSbTHkbKbYEfDJ7MGb6_pllGWd1VQ-JxQI7UDLvYrCUH9o7i1rOSeSG8zJewZw; expires=Thu, 27 Mar 2025 10:22:49 GMT; domain=apiexamples.myvtex.com; path=/api/vtexid/refreshtoken/webstore; secure; samesite=strict; httponly" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/validateSessionResponse" }, "example": { "authStatus": "Success", "promptMFA": false, "lastAttemptAvailable": null, "clientToken": null, "authCookie": { "Name": "VtexIdclientAutCookie_apiexamples", "Value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" }, "accountAuthCookie": { "Name": "VtexIdclientAutCookie_a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "Value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" }, "expiresIn": 86399, "userId": "1f6c17e5-06f9-44a9-a459-b3686e03fa9d", "phoneNumber": null, "scope": null } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/validateSessionResponse" }, "example": { "authStatus": "InvalidEmail", "promptMFA": false, "lastAttemptAvailable": null, "clientToken": null, "authCookie": null, "accountAuthCookie": null, "expiresIn": 0, "userId": null, "phoneNumber": null, "scope": null } } } } } } }, "/api/vtexid/refreshtoken/webstore": { "servers": [ { "url": "https://{storeDomain}", "description": "Store domain.", "variables": { "storeDomain": { "description": "Store domain.", "default": "apiexamples.com" } } }, { "url": "https://{accountName}.{environment}.com", "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": [ "myvtex" ], "default": "myvtex" } } } ], "post": { "tags": [ "Refresh token headless" ], "summary": "Refresh token", "description": "Returns a valid refresh token and authentication token (`VtexIdclientAutCookie`) as cookies.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "Host", "in": "header", "description": "Host address.", "required": true, "schema": { "type": "string", "example": "apiexamples.myvtex.com" } }, { "name": "vid_rt", "in": "cookie", "description": "Refresh token obtained in the [Validate session](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/vtexid/pub/authentication/accesskey/validate) request.", "required": true, "schema": { "type": "string", "example": "QiEOQKuzdRjukvSnsn7F8h1wwkrqq8wWlkk7bXA5LSbTHkbKbYEfDJ7MGb6_pllGWd1VQ-JxQI7UDLvYrCUH9o7i1rOSeSG8zJewZw" } }, { "name": "VtexIdclientAutCookie_{{accountId}}", "in": "cookie", "description": "Account auth cookie.", "required": true, "schema": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" } }, { "name": "VtexIdclientAutCookie_{{accountName}}", "in": "cookie", "description": "Auth cookie.", "required": true, "schema": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "fingerprint": { "type": "string", "description": "Optional device fingerprint for enhanced security. Generated client-side using JavaScript libraries that collect anonymized device and browser parameters to create a unique identifier. Must remain consistent with the fingerprint provided during [initial authentication](https://developers.vtex.com/docs/api-reference/vtex-id-api#get-/api/vtexid/pub/authentication/start), if previously submitted.", "nullable": true } } }, "example": { "fingerprint": "12345" } } } }, "responses": { "200": { "description": "OK", "headers": { "Set-Cookie": { "schema": { "type": "string", "description": "Valid refresh token." } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Refresh token response object.", "properties": { "status": { "type": "string", "description": "Status of the operation. Possible values: \r\n- `Success`: Token refresh was successful. \r\n- `InvalidSession`: The session is invalid or expired. \r\n- `InvalidToken`: The token is invalid. \r\n- `InvalidEmail`: The email associated with the token is invalid. \r\n- `InvalidScope`: The scope is invalid.", "enum": [ "Success", "InvalidSession", "InvalidToken", "InvalidEmail", "InvalidScope" ] }, "userId": { "type": "string", "description": "Unique identifier assigned to the authenticated user." }, "refreshAfter": { "type": "string", "format": "date-time", "description": "The timestamp indicating when the session should be refreshed, in ISO 8601 format (`YYYY-MM-DDTHH:mm:ss±HH:MM`)." } } }, "example": { "status": "Success", "userId": "1f6c17e5-06f9-44a9-a459-b3686e03fa9d", "refreshAfter": "2025-03-27T02:36:30+00:00" } } } } } } }, "/api/vtexid/organization-units/{unitId}/settings": { "get": { "tags": [ "Organization account authentication" ], "summary": "Get organization unit authentication settings", "description": "Returns the authentication methods configured for an organization unit, such as password login and external identity provider (SSO), including whether each method is enabled.\r\n\r\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/en/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\r\n\r\n>ℹ️ These endpoints configure authentication methods for an organization unit (for example password or SSO). To manage unit hierarchy and membership, use the [Organization Units API](https://developers.vtex.com/docs/api-reference/organization-units-api). For more information about organization units, see [Organization units](https://help.vtex.com/docs/tutorials/organizational-units). Send the `VtexIdclientAutCookie` user token header, or the `X-VTEX-API-AppKey` and `X-VTEX-API-AppToken` headers.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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| Organization Units | units | **View_Organization_Unit** |\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>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "unitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit whose authentication settings are being read.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK\n\nAuthentication settings were returned successfully.", "content": { "application/json": { "schema": { "type": "object", "description": "Authentication settings for the organization unit.", "required": [ "authenticationMethods" ], "properties": { "authenticationMethods": { "type": "array", "description": "List of authentication methods available for the organization unit.", "items": { "type": "object", "description": "Single authentication method entry.", "required": [ "type", "name", "status" ], "properties": { "type": { "type": "string", "description": "Machine-readable authentication method type: `Password` for password login or `OAuth` for SSO through an external identity provider.", "enum": [ "Password", "OAuth" ] }, "name": { "type": "string", "description": "Human-readable label of the method, such as the configured identity provider name." }, "status": { "type": "string", "description": "Whether the method is enabled for this organization unit.", "enum": [ "Enabled", "Disabled" ] } } } } } }, "example": { "authenticationMethods": [ { "type": "Password", "name": "Password", "status": "Enabled" }, { "type": "OAuth", "name": "PingFederate", "status": "Enabled" } ] } } } }, "401": { "description": "Unauthorized\n\nThe current user could not be resolved.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the authenticated user cannot be resolved.", "properties": { "message": { "type": "string", "description": "Explanation of why the request is unauthorized." } } }, "example": { "message": "The current user could not be resolved." } } } }, "403": { "description": "Forbidden\n\nAccess denied.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the caller is not allowed to access this resource.", "properties": { "message": { "type": "string", "description": "Explanation of why access was denied." } } }, "example": { "message": "Access denied." } } } }, "404": { "description": "Not Found\n\nInvalid organization unit ID or the organization unit was not found.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the organization unit cannot be found or the path parameter is invalid.", "properties": { "message": { "type": "string", "description": "Explanation of why the resource was not found." } } }, "example": { "message": "Organization unit not found." } } } }, "500": { "description": "Internal Server Error\n\nUnknown server error.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the server fails to process the request.", "properties": { "message": { "type": "string", "description": "Explanation of the server error." } } }, "example": { "message": "An unexpected error occurred." } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ] }, "post": { "tags": [ "Organization account authentication" ], "summary": "Set organization unit authentication settings", "description": "Defines authentication settings for an organization unit, for example enabling or disabling SSO for a configured external identity provider. Send each method to change using its display `name` and desired `status`.\r\n\r\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/en/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\r\n\r\n>ℹ️ These endpoints configure authentication methods for an organization unit (for example password or SSO). To manage unit hierarchy and membership, use the [Organization Units API](https://developers.vtex.com/docs/api-reference/organization-units-api). For more information about organization units, see [Organization units](https://help.vtex.com/docs/tutorials/organizational-units). Send the `VtexIdclientAutCookie` user token header, or the `X-VTEX-API-AppKey` and `X-VTEX-API-AppToken` headers.\r\n\r\n## Prerequisites\r\n\r\nBefore enabling login via external IdP, ensure the following requirements are met:\r\n\r\n- The identity provider must be previously configured in the VTEX Admin. Learn more in [Login (SSO)](https://developers.vtex.com/docs/guides/login-integration-guide) and [Webstore (OAuth 2.0)](https://developers.vtex.com/docs/guides/login-integration-guide-webstore-oauth2).\r\n- The [vtex.login-alternative-key](https://developers.vtex.com/docs/apps/vtex.login-alternative-key) app must be installed in the store.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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| Organization Units | units | **Edit_Organization_Unit** |\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>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "unitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit whose authentication settings are being updated.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Payload listing authentication methods to update by display name and status.", "required": [ "settings" ], "properties": { "settings": { "type": "array", "description": "Authentication methods to update for the organization unit.", "items": { "type": "object", "description": "Update entry for one authentication method.", "required": [ "type", "name", "status" ], "properties": { "type": { "type": "string", "description": "Machine-readable authentication method type: `Password` for password login or `OAuth` for SSO through an external identity provider.", "enum": [ "Password", "OAuth" ] }, "name": { "type": "string", "description": "Display name of the authentication method to update, as returned by `GET` [Get organization unit authentication settings](https://developers.vtex.com/docs/api-reference/vtex-id-api#get-/api/vtexid/organization-units/-unitId-/settings) (for example the identity provider name for SSO)." }, "status": { "type": "string", "description": "Target status for the method.", "enum": [ "Enabled", "Disabled" ] } } } } } }, "example": { "settings": [ { "type": "OAuth", "name": "PingFederate", "status": "Disabled" } ] } } } }, "responses": { "200": { "description": "OK\n\nSettings were updated successfully.", "content": { "application/json": { "schema": { "type": "object", "description": "Acknowledgement of a successful update.", "properties": { "success": { "type": "boolean", "description": "Indicates that the update completed without errors." } } }, "example": { "success": true } } } }, "400": { "description": "Bad Request\n\nInvalid authentication configuration.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the request body does not describe a valid authentication configuration.", "properties": { "message": { "type": "string", "description": "Explanation of why the configuration is invalid." } } }, "example": { "message": "Invalid authentication configuration." } } } }, "401": { "description": "Unauthorized\n\nThe current user could not be resolved.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the authenticated user cannot be resolved.", "properties": { "message": { "type": "string", "description": "Explanation of why the request is unauthorized." } } }, "example": { "message": "The current user could not be resolved." } } } }, "403": { "description": "Forbidden\n\nAccess denied.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the caller is not allowed to perform this operation.", "properties": { "message": { "type": "string", "description": "Explanation of why access was denied." } } }, "example": { "message": "Access denied." } } } }, "404": { "description": "Not Found\n\nInvalid organization unit ID or the organization unit was not found.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the organization unit cannot be found or the path parameter is invalid.", "properties": { "message": { "type": "string", "description": "Explanation of why the resource was not found." } } }, "example": { "message": "Organization unit not found." } } } }, "409": { "description": "Conflict\n\nAuthentication settings already exist for one or more methods.", "content": { "application/json": { "schema": { "type": "object", "description": "Conflict error details when settings already exist for one or more authentication methods.", "properties": { "message": { "type": "string", "description": "Human-readable reason for the conflict." } } }, "example": { "message": "Authentication settings already exist for one or more methods." } } } }, "500": { "description": "Internal Server Error\n\nUnknown server error.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the server fails to process the request.", "properties": { "message": { "type": "string", "description": "Explanation of the server error." } } }, "example": { "message": "An unexpected error occurred." } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ] }, "patch": { "tags": [ "Organization account authentication" ], "summary": "Update organization unit authentication settings", "description": "Partially updates authentication configurations that already exist for the organization unit (for example changing `status`). This endpoint doesn't create new authentication methods; use `POST` [Set organization unit authentication settings](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/vtexid/organization-units/-unitId-/settings) to define or add them.\r\n\r\nSend a `settings` array in which each object specifies the configuration `type` (for example `OAuth`) and the desired `status` for that existing configuration.\r\n\r\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/en/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\r\n\r\n>ℹ️ These endpoints configure authentication methods for an organization unit (for example password or SSO). To manage unit hierarchy and membership, use the [Organization Units API](https://developers.vtex.com/docs/api-reference/organization-units-api). For more information about organization units, see [Organization units](https://help.vtex.com/docs/tutorials/organizational-units). Send the `VtexIdclientAutCookie` user token header, or the `X-VTEX-API-AppKey` and `X-VTEX-API-AppToken` headers.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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| Organization Units | units | **Edit_Organization_Unit** |\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>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "unitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit whose authentication settings are being patched.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Payload listing existing authentication configuration entries to update by type and target status.", "required": [ "settings" ], "properties": { "settings": { "type": "array", "description": "Authentication configuration entries to partially update for the organization unit.", "items": { "type": "object", "description": "Update entry for one authentication configuration.", "required": [ "type", "status" ], "properties": { "type": { "type": "string", "description": "Authentication configuration category to update.", "enum": [ "OAuth" ] }, "status": { "type": "string", "description": "Target status for the configuration.", "enum": [ "Enabled", "Disabled" ] } } } } } }, "example": { "settings": [ { "type": "OAuth", "status": "Disabled" } ] } } } }, "responses": { "200": { "description": "OK\n\nUpdated authentication settings were returned successfully.", "content": { "application/json": { "schema": { "type": "object", "description": "Authentication settings for the organization unit.", "required": [ "authenticationMethods" ], "properties": { "authenticationMethods": { "type": "array", "description": "List of authentication methods available for the organization unit.", "items": { "type": "object", "description": "Single authentication method entry.", "required": [ "type", "name", "status" ], "properties": { "type": { "type": "string", "description": "Machine-readable authentication method type: `Password` for password login or `OAuth` for SSO through an external identity provider.", "enum": [ "Password", "OAuth" ] }, "name": { "type": "string", "description": "Human-readable label of the method, such as the configured identity provider name." }, "status": { "type": "string", "description": "Whether the method is enabled for this organization unit.", "enum": [ "Enabled", "Disabled" ] } } } } } }, "example": { "authenticationMethods": [ { "type": "Password", "name": "Password", "status": "Enabled" }, { "type": "OAuth", "name": "PingFederate", "status": "Enabled" } ] } } } }, "400": { "description": "Bad Request\n\nInvalid authentication configuration or authentication settings were not found for update.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the request is invalid or existing settings cannot be updated.", "properties": { "message": { "type": "string", "description": "Explanation of why the request failed validation or could not be applied." } } }, "example": { "message": "Authentication settings were not found for update." } } } }, "401": { "description": "Unauthorized\n\nThe current user could not be resolved.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the authenticated user cannot be resolved.", "properties": { "message": { "type": "string", "description": "Explanation of why the request is unauthorized." } } }, "example": { "message": "The current user could not be resolved." } } } }, "403": { "description": "Forbidden\n\nAccess denied.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the caller is not allowed to perform this operation.", "properties": { "message": { "type": "string", "description": "Explanation of why access was denied." } } }, "example": { "message": "Access denied." } } } }, "404": { "description": "Not Found\n\nInvalid organization unit ID or the organization unit was not found.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the organization unit cannot be found or the path parameter is invalid.", "properties": { "message": { "type": "string", "description": "Explanation of why the resource was not found." } } }, "example": { "message": "Organization unit not found." } } } }, "500": { "description": "Internal Server Error\n\nUnknown server error.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the server fails to process the request.", "properties": { "message": { "type": "string", "description": "Explanation of the server error." } } }, "example": { "message": "An unexpected error occurred." } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ] }, "delete": { "tags": [ "Organization account authentication" ], "summary": "Delete organization unit authentication setting", "description": "Deletes only the authentication configuration entries listed in the request body `settings` array (each entry is identified by `type`, for example `OAuth`). Other organization unit authentication configuration is not removed. Use with care when deleting unit-specific SSO configuration.\r\n\r\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/en/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\r\n\r\n>ℹ️ These endpoints configure authentication methods for an organization unit (for example password or SSO). To manage unit hierarchy and membership, use the [Organization Units API](https://developers.vtex.com/docs/api-reference/organization-units-api). For more information about organization units, see [Organization units](https://help.vtex.com/docs/tutorials/organizational-units). Send the `VtexIdclientAutCookie` user token header, or the `X-VTEX-API-AppKey` and `X-VTEX-API-AppToken` headers.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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| Organization Units | units | **Edit_Organization_Unit** |\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>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "unitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit from which the listed authentication settings will be deleted.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Payload listing authentication configuration types to delete for the organization unit.", "required": [ "settings" ], "properties": { "settings": { "type": "array", "description": "Authentication configuration entries to delete.", "items": { "type": "object", "description": "Single entry identifying which authentication configuration type to delete.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Authentication configuration category to delete.", "enum": [ "OAuth", "Password" ] } } } } } }, "example": { "settings": [ { "type": "OAuth" } ] } } } }, "responses": { "204": { "description": "No Content\n\nThe listed authentication configuration entries were deleted successfully." }, "400": { "description": "Bad Request\n\nInvalid authentication configuration or authentication settings were not found for delete.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the request is invalid or settings cannot be deleted.", "properties": { "message": { "type": "string", "description": "Explanation of why the request failed validation or settings could not be removed." } } }, "example": { "message": "Authentication settings were not found for delete." } } } }, "401": { "description": "Unauthorized\n\nThe current user could not be resolved.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the authenticated user cannot be resolved.", "properties": { "message": { "type": "string", "description": "Explanation of why the request is unauthorized." } } }, "example": { "message": "The current user could not be resolved." } } } }, "403": { "description": "Forbidden\n\nAccess denied.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the caller is not allowed to perform this operation.", "properties": { "message": { "type": "string", "description": "Explanation of why access was denied." } } }, "example": { "message": "Access denied." } } } }, "404": { "description": "Not Found\n\nInvalid organization unit ID or the organization unit was not found.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the organization unit cannot be found or the path parameter is invalid.", "properties": { "message": { "type": "string", "description": "Explanation of why the resource was not found." } } }, "example": { "message": "Organization unit not found." } } } }, "500": { "description": "Internal Server Error\n\nUnknown server error.", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload when the server fails to process the request.", "properties": { "message": { "type": "string", "description": "Explanation of the server error." } } }, "example": { "message": "An unexpected error occurred." } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ] } } }, "components": { "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" } }, "an": { "name": "an", "in": "query", "description": "Name of your VTEX account.", "required": false, "style": "form", "schema": { "type": "string", "example": "exampleAccount" } }, "accountName": { "name": "accountName", "in": "path", "required": true, "description": "Name of your VTEX account.", "schema": { "type": "string", "example": "apiexamples" } }, "environment": { "name": "environment", "in": "path", "required": true, "description": "Environment to be used in the request.", "schema": { "type": "string", "default": "vtexcommercestable" } }, "apiKey": { "name": "apiKey", "in": "path", "description": "API Key name.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } }, "schemas": { "credentials": { "type": "object", "description": "Credentials object, composed of API key and application token.", "required": [ "appkey", "apptoken" ], "properties": { "appkey": { "type": "string", "description": "API key.", "example": "vtexappkey-example-YSWQFZ" }, "apptoken": { "type": "string", "description": "Application token corresponding to the API key sent with it.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjA1MTZFN0IwMDNFODMxRTg0QkFDOTg2NzBCNUM2QTRERTlBN0RFNkUiLCJ0eXAiOiJqd3QifQ.eyJzdWIiOiJwZWRyby5jb3N0YUB2dGV4LmNvbS5iciIsImFjY291bnQiOiJhcHBsaWFuY2V0aGVtZSIsImF1ZGllbmNlIjoiYWRtaW4iLCJzZXNzIjoiZjU3YjMyMGItMWE3YS00YzlkLWJkNDMtZTE4NDdhYmE1MTE1IiwiZXhwIjoxNjE2NzY3Mjc4LCJ1c2VySWQiOiJmYjU0MmU1MS01NDg4LTRjMzQtOGQxNy1lZDhmY2Y1OTdhOTQiLCJpYXQiOjE2MwerY2ODA4NzgsImlzcyI6InRva2VuLWVtaXR0ZXIiLCJqdGkiOiJmYTI0YWJiOC03Y2E5LTQ3NjUtYmYzNC1kMmvU5YTgzYjYxZmUifQ.23rn-2dEdAAYXJX2exrxDEdbieyKWsVKABeSUNeFWyhz7xRd7d5EcxwiMLjM3bRaBOKrAA9Op7ocn89c45qQ" } } }, "validateSessionResponse": { "type": "object", "description": "Validate session response object.", "properties": { "authStatus": { "type": "string", "description": "Authentication status of the user, which can be: \n\n* `Success`: when authentication is completed successfully.\n* `InvalidEmail`: When the email informed is not valid.\n* `InvalidToken`: When the token is malformed, expired, or has an invalid signature.\n* `WrongCredentials`: When the informed credentials are not valid.", "enum": [ "Success", "InvalidEmail", "InvalidToken", "WrongCredentials" ] }, "promptMFA": { "type": "boolean", "description": "Indicates whether multi-factor authentication is required." }, "lastAttemptAvailable": { "type": "integer", "nullable": true, "description": "Last authentication attempt available." }, "clientToken": { "type": "string", "nullable": true, "description": "Client token." }, "authCookie": { "type": "object", "nullable": true, "description": "Authentication cookie.", "properties": { "Name": { "type": "string", "description": "Name of the cookie." }, "Value": { "type": "string", "description": "Value of the cookie." } } }, "accountAuthCookie": { "type": "object", "nullable": true, "description": "Cookie specific to account authentication.", "properties": { "Name": { "type": "string", "description": "Name of the cookie." }, "Value": { "type": "string", "description": "Value of the cookie." } } }, "expiresIn": { "type": "integer", "description": "Time in seconds until authentication expires." }, "userId": { "type": "string", "nullable": true, "description": "Unique identifier for the authenticated user." }, "phoneNumber": { "type": "string", "nullable": true, "description": "User's phone number associated with the account." }, "scope": { "type": "string", "nullable": true, "description": "Authentication scope granted." } } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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." } } }, "tags": [ { "name": "Authentication" }, { "name": "Token renewal" }, { "name": "Refresh token headless" }, { "name": "Storefront users" }, { "name": "Organization account authentication" } ], "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ] }