VTEX App Keys API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account App Keys 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: App Keys
paths:
  /api/vlm/appkeys:
    post:
      tags:
      - App Keys
      summary: VTex Create new appKey
      description: "Creates a new pair of `appKey` and `appToken`. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-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| License Manager | Services access control | **Save user** |\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 | Save user |\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-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      operationId: Createnewappkey
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatenewappkeyRequest'
            example:
              label: my new appkey
        required: true
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatenewappkeyResponse'
              example:
                id: a2555e95-9db8-48be-94f8-2a28577c0b4a
                appKey: vtexappkey-myaccount-ORYNWX
                appToken: WNVUJKYFKJFLTPXHQGAZDHPBHSDQVJJWSFZUBOGCKPEXAIFHTPANKJTOXUKRIIJAAJSOPCFBAXOODRABMUXFJVLJLKWGEOUCFDXRPRRQKYNNUFLGTIEOKERFXJCFFYXL
                label: my new appkey
                createdIn: '2018-07-04T14:09:08.2718405Z'
                isActive: true
      deprecated: false
    get:
      tags:
      - App Keys
      summary: VTex Get appKeys from account
      description: "Retrieves all application keys from an account. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-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| License Manager | Services access control | **Save user** |\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 | Save user |\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-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      operationId: Getappkeysfromaccount
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                type: array
                description: Array of AppKeys object
                items:
                  $ref: '#/components/schemas/Getappkeysfromaccount'
              example:
              - id: a2555e95-9db8-48be-94f8-2a28577c0b4a
                appKey: vtexappkey-myaccount-ORYNWX
                label: my new appkey
                createdIn: '2018-07-04T14:09:08.2718405Z'
                isActive: true
              - id: a2555e95-9db8-48be-94f8-2a28577c0b4a
                appKey: vtexappkey-myaccount-ORKPDC
                label: my other appkey
                createdIn: '2018-07-04T14:09:08.2718405Z'
                isActive: true
      deprecated: false
  /api/vlm/appkeys/{id}:
    put:
      tags:
      - App Keys
      summary: VTex Update appKey
      description: "Activates or deactivates an `appKey` by its ID. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-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| License Manager | Services access control | **Save user** |\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 | Save user |\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-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      operationId: Updateappkey
      parameters:
      - name: id
        in: path
        description: ID from the appKey which will be updated
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: Request body for updating AppKeys
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateappkeyRequest'
            example:
              isActive: false
        required: true
      responses:
        '200':
          description: Success
          headers: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VLMError'
              example:
                Details: null
                HttpStatusCode: 400
                VLMErrorCode: 17
                Message: Token not exists for this account
      deprecated: false
components:
  schemas:
    VLMError:
      description: Object representing VLMError.
      type: object
      properties:
        Details:
          description: Details of error.
          type: string
          nullable: true
        HttpStatusCode:
          description: Status code of HTTP response.
          type: integer
        VLMErrorCode:
          description: Error code for License Manager.
          type: integer
        Message:
          description: Error message.
          type: string
    UpdateappkeyRequest:
      description: Request body for activating or deactivating application keys.
      required:
      - isActive
      type: object
      properties:
        isActive:
          description: Defines if the application key is active (`true`) or not (`false`).
          type: boolean
          example: true
    Getappkeysfromaccount:
      description: Response body for getting all application keys from the account.
      required:
      - id
      - appKey
      - label
      - createdIn
      - isActive
      type: object
      properties:
        id:
          description: ID of the application key.
          type: string
        appKey:
          description: AppKey.
          type: string
        label:
          description: Label of the application key.
          type: string
        createdIn:
          description: Creation date of the application key.
          type: string
          format: date-time
        isActive:
          description: Defines if the application key is active (`true`) or not (`false`).
          type: boolean
    CreatenewappkeyResponse:
      description: Response body of sucessful call to /api/vlm/appkeys.
      required:
      - id
      - appKey
      - appToken
      - label
      - createdIn
      - isActive
      type: object
      properties:
        id:
          description: ID of the application key.
          type: string
        appKey:
          description: AppKey.
          type: string
        appToken:
          description: AppToken. For security reasons, it should always be null.
          type: string
          nullable: true
        label:
          description: Label of the application key.
          type: string
        createdIn:
          description: Creation date of the application key.
          type: string
          format: date-time
        isActive:
          description: Defines if the application key is active (`true`) or not (`false`).
          type: boolean
    CreatenewappkeyRequest:
      description: Request body for creating new application key (/api/vlm/appkeys)
      required:
      - label
      type: object
      properties:
        label:
          description: Label of the application key.
          type: string
          example: appkey-test
  parameters:
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
  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.'