VTEX Authentication API

openapi: 3.2.0
info:
  title: Vtex Authentication API
  version: '1.0'
  description: 'Operations tagged Authentication across 3 of this provider''s published API definitions: vtex-id-openapi-original.yml, vtex-pick-pack-last-mile-protocol-openapi-original.yml, vtex-tracking-openapi-original.yml. Each path carries the servers of the definition it was published in.'
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://auth.pickingnpacking.com/{environment}
  variables:
    environment:
      default: DefaultParameterValue
      description: Server to access the authentication necessary to make a request in the Pick and Pack Provider API.
- url: https://{store_endpoint}
  variables:
    your_endpoint:
      default: storeapi.com
      description: Server from the store.
- url: https://api.pickingnpacking.com/{environment}/v1/tracking/hook
  variables:
    environment:
      default: DefaultParameterValue
      description: Environment of the Pick and Pack Protocol App.
- url: https://api.vtextracking.com/receiver
  variables:
    api.vtextracking.com:
      default: api.vtextracking.com
tags:
- name: Authentication
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\n> Since you are sending the credentials on the request body, there is no need to send authentication headers. \n\n> 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.\n\n## Permissions\n\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
      security:
      - appKey: []
        appToken: []
      - VtexIdclientAutCookie: []
    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
  /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.


        Learn more about how to implement [headless authentication](https://developers.vtex.com/docs/guides/headless-authentication) in your store.


        ## Permissions


        This 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
      security:
      - appKey: []
        appToken: []
      - VtexIdclientAutCookie: []
    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
  /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)`.


        ## Permissions


        This 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: 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
      security:
      - appKey: []
        appToken: []
      - VtexIdclientAutCookie: []
    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
  /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. \n\n## Permissions\n\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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| VTEX ID | Identity Providers | **Write Identity Providers** |\n\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.\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\n\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
      security:
      - appKey: []
        appToken: []
      - VtexIdclientAutCookie: []
    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
  /api/vtexid/password/expire:
    post:
      tags:
      - Authentication
      summary: VTex Expire user password
      description: 'Expires an user''s password in your store.


        ## Permissions


        Any 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | VTEX ID | User Management | **Expire User Password** |


        There 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.

        To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).


        >❗ 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@email.com
      responses:
        '200':
          description: OK
      security:
      - appKey: []
        appToken: []
      - VtexIdclientAutCookie: []
    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
  /token:
    post:
      tags:
      - Authentication
      summary: VTex Create JWT token
      description: 'Creates a `JWT` (JSON Web Token) necessary to access the Pick and Pack Last Mile Protocol API information.


        >ℹ️ To generate the `JWT` it is necessary to have the `API KEY` previously generated by the Pick and Pack team.


        ## Permissions


        This endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).'
      operationId: Createtoken
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatetokenRequest'
            example:
              apiKey: '{pnpApiKey}'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
                description: Generated `JWT` token.
              example: '{token}'
      deprecated: false
      servers:
      - url: https://auth.pickingnpacking.com/{environment}
        variables:
          environment:
            default: DefaultParameterValue
            description: Server to access the authentication necessary to make a request in the Pick and Pack Last Mile Protocol API.
    servers:
    - url: https://auth.pickingnpacking.com/{environment}
      variables:
        environment:
          default: DefaultParameterValue
          description: Server to access the authentication necessary to make a request in the Pick and Pack Provider API.
    - url: https://{store_endpoint}
      variables:
        your_endpoint:
          default: storeapi.com
          description: Server from the store.
    - url: https://api.pickingnpacking.com/{environment}/v1/tracking/hook
      variables:
        environment:
          default: DefaultParameterValue
          description: Environment of the Pick and Pack Protocol App.
  /auth:
    post:
      tags:
      - Authentication
      summary: VTex Asynchronous Login
      description: "This endpoint permits the user to acquire the mandatory authentication to access the VTEX Tracking endpoints. \n> There is a single version of VTEX Tracking API, so it is no longer necessary to specify the version on the URL, as explained in this [release note](https://developers.vtex.com/updates/release-notes/vtex-tracking-api-changes-in-all-paths). The previous routes were not deprecated and can still be used, and if there is a breaking change, it will be informed."
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: Accept
        in: header
        description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              title: Request body
              default:
                username: clientUserName
                password: 32gv34fs
              required:
              - username
              - password
              properties:
                username:
                  type: string
                  description: Add client's username
                  default: username
                password:
                  type: string
                  description: Add client's password
                  default: password
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Unauthorized
      deprecated: false
    servers:
    - url: https://api.vtextracking.com/receiver
      variables:
        api.vtextracking.com:
          default: api.vtextracking.com
components:
  parameters:
    accountName:
      name: accountName
      in: path
      required: true
      description: Name of your VTEX account.
      schema:
        type: string
        example: apiexamples
    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
    environment:
      name: environment
      in: path
      required: true
      description: Environment to be used in the request.
      schema:
        type: string
        default: vtexcommercestable
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      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
  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
    CreatetokenRequest:
      required:
      - apiKey
      type: object
      properties:
        apiKey:
          type: string
          description: The `API KEY` previously generated by the Pick and Pack team. To contact the team, fill out our [form](https://vtex.com/us-en/contact) and indicate the name of the Pick and Pack product in the `Comments` section.
      example:
        apiKey: '{pnpApiKey}'
    TokenResponse:
      title: TokenResponse
      type: object
      properties:
        authenticated:
          type: boolean
        created:
          type: string
        expiration:
          type: string
        accessToken:
          type: string
        message:
          type: string
  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.'
    Authorization:
      type: http
      scheme: bearer
      description: To use the endpoints, please login through the Authentication API, and copy the access token in the response.
x-refined-from:
- vtex-id-openapi-original.yml
- vtex-pick-pack-last-mile-protocol-openapi-original.yml
- vtex-tracking-openapi-original.yml