VTEX ID API
The VTEX ID API provides authentication and identity management for VTEX stores. It handles user login, token generation, authentication renewal, and password management for customers, store operators, and API integrations.
OpenAPI Specification
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.\r\n\r\n## Index\r\n\r\n- `POST` [Generate authentication token](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/vtexid/apptoken/login)\r\n- `POST` [Check authenticated user](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/vtexid/credential/validate)\r\n- `POST` [Enable or disable repeated passwords](https://developers.vtex.com/docs/api-reference/vtex-id-api#get-/api/vtexid/pub/providers/setup/password/webstore/password)\r\n- `POST` [Expire user password](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/vtexid/password/expire)"
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
paths:
/api/vtexid/apptoken/login:
post:
tags:
- Authentication
summary: VTex 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/application-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/application-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'
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 time in seconds.
example:
authStatus: Success
token: eyJhbGciOiJFUzI1NiIsImtpZCI6IjFBRjI5MUUwRDY0MERENTlEQTkzRTg0REMxNjQyNjA3ODZEQjY3ODAiLCJ0eXAiOiJqd3QifQ.eyJzdWIiOiJ2dGV4YXBwa2V5LXZ0ZXhoZWxwLVdWQ0FCVCIsImFjY291bnQiOiJwerV4aGVscCIsImF1ZGllbmNlIjoiYWRtaW4iLCJleHAiOjE2Njk3NzA3MzcsInVzZXJJZCI6IjM5MjNhMmUy5khmMTctNGNiYy04YzU3LWQ3OGFkNmUxYTU2NiIsImlhdCI6MTY2OTc0OTEzNywiaXNzIjoidG9rZW4tZW1HgoRlciIsImp0aSI6IjNiNjAxODA2LTExMzEtNDcwYS05MWJjLTVhM2JhOThiYWQyNiJ9.Q7N8MFa1FMJsQUpxBY29oije4aa-Jf29wgLFLl6LUY3Wei3MRUVUMRQWkey6Kug8iFPonZ1L-PaFmwfzSz3TCQ
expires: 1669770737
/api/vtexid/audience/webstore/provider/oauth/exchange:
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.
example: GoogleID
accessToken:
type: string
description: Access token obtained from your frontend via OAuth integration corresponding with the indicated `providerId`.
example: dsfDShdgfhDFI1NiIsIrtyZCI6IjFBRjI5MUUwRDY0MERENTlEQTkzRTg0REMxNjQyNjA3ODZEQjY3ODAiLCJ0eXAiOiJqd3QifQ.eyJzdWIiOiJ2dGV4YXBwa2V5LXZ0ZXhoZWxwLVdWQ0FCVCIsImFjY291bdg465DATU4GVscCIsImF1MBllbmNlIjoiYWRtaW4iLCJleHAiOjE2Njk3NzA3MzcsInVzZXJJZCI6IjM5MjNhMmUy5khmMTctNGNiYy04YzU3LWQ3OGFkNmUxYTU2NiIsImlhdCI6MTY2OTc0OTEzNywiaXNzIjoidG9rZW4tZW1HgoRlciIsImp0aSI6IjNiNjAxODA2LTExMzEtNDcwYS05MWJjLTVhM2JhOThiYWQyNiJ9.Q7N8MFa1FMJsQUpxBY29oije4aa-654fgjLFLl6LUY3Wei3MRUVUMRQWkey6Kug8iFPonZ1L-PaFmwfzSz3TCQ
duration:
type: integer
description: Duration of the token that will be returned, in minutes.
example: 90
default: 60
responses:
'200':
description: 200 - 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:
post:
tags:
- Authentication
summary: VTex 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: 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: [email protected]
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:
post:
tags:
- Authentication
summary: VTex 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 [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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`).
example: true
allowRepeated:
type: boolean
description: Defines if passwords can be repeated (`true`) or not (`false`).
example: false
responses:
'200':
description: OK
/api/vtexid/password/expire:
post:
tags:
- Authentication
summary: VTex Expire user password
description: "Expires an user's password in your store.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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 protected]
responses:
'200':
description: OK
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
schemas:
credentials:
type: object
description: Credentials object, composed of application key and application token.
required:
- appkey
- apptoken
properties:
appkey:
type: string
description: Application key.
example: vtexappkey-example-YSWQFZ
apptoken:
type: string
description: Application token corresponding to the application key sent with it.
example: eyJhbGciOiJFUzI1NiIsImtpZCI6IjA1MTZFN0IwMDNFODMxRTg0QkFDOTg2NzBCNUM2QTRERTlBN0RFNkUiLCJ0eXAiOiJqd3QifQ.eyJzdWIiOiJwZWRyby5jb3N0YUB2dGV4LmNvbS5iciIsImFjY291bnQiOiJhcHBsaWFuY2V0aGVtZSIsImF1ZGllbmNlIjoiYWRtaW4iLCJzZXNzIjoiZjU3YjMyMGItMWE3YS00YzlkLWJkNDMtZTE4NDdhYmE1MTE1IiwiZXhwIjoxNjE2NzY3Mjc4LCJ1c2VySWQiOiJmYjU0MmU1MS01NDg4LTRjMzQtOGQxNy1lZDhmY2Y1OTdhOTQiLCJpYXQiOjE2MwerY2ODA4NzgsImlzcyI6InRva2VuLWVtaXR0ZXIiLCJqdGkiOiJmYTI0YWJiOC03Y2E5LTQ3NjUtYmYzNC1kMmvU5YTgzYjYxZmUifQ.23rn-2dEdAAYXJX2exrxDEdbieyKWsVKABeSUNeFWyhz7xRd7d5EcxwiMLjM3bRaBOKrAA9Op7ocn89c45qQ
securitySchemes:
appKey:
type: apiKey
in: header
name: X-VTEX-API-AppKey
description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
appToken:
type: apiKey
in: header
name: X-VTEX-API-AppToken
description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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
security:
- appKey: []
appToken: []
- VtexIdclientAutCookie: []