VTEX Authentication API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Authentication API
  description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud  Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)"
  version: '1.0'
servers:
- url: https://{providerApiEndpoint}
  description: Anti-fraud provider endpoint URL.
  variables:
    providerApiEndpoint:
      description: Anti-fraud provider endpoint URL.
      default: '{providerApiEndpoint}'
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\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: 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:
    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@email.com
      responses:
        '200':
          description: OK
  /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.\r\n\r\n>ℹ️ To generate the `JWT` it is necessary to have the `API KEY` previously generated by the Pick and Pack team.\r\n\r\n## Permissions\r\n\r\nThis 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.
  /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. \r\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
components:
  parameters:
    accountName:
      name: accountName
      in: path
      required: true
      description: Name of your VTEX account.
      schema:
        type: string
        example: apiexamples
    an:
      name: an
      in: query
      description: Name of your VTEX account.
      required: false
      style: form
      schema:
        type: string
        example: exampleAccount
    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
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      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
  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
    TokenResponse:
      title: TokenResponse
      type: object
      properties:
        authenticated:
          type: boolean
        created:
          type: string
        expiration:
          type: string
        accessToken:
          type: string
        message:
          type: string
    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}'
  securitySchemes:
    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.'