VTEX Users API

openapi: 3.2.0
info:
  title: VTex License Manager Users API
  description: 'The License Manager API allows you to create users, modify their names and emails, add and remove [roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) from users, and create and manage [appKeys](https://help.vtex.com/en/tutorial/application-keys--2iffYzlvvz4BDMr6WGUtet).


    ## Common parameters


    |Attribute name | Description |

    |:------------|--------------|

    |`accountName` | Account name in VTEX License Manager. |

    |`environment` | Environment on which you want to run the query, e.g. `vtexcommercestable`. |

    |`userId`      | Unique user identification string. |

    |`roleId`      | Integer that represents a role, can be obtained from the [Get List of Roles](https://developers.vtex.com/docs/api-reference/license-manager-api#get-/api/license-manager/site/pvt/roles/list/paged) endpoint. |


    ## Index


    ### User


    - `GET` [Get user](https://developers.vtex.com/docs/api-reference/license-manager-api#get-/api/license-manager/users/-userId-)

    - `DELETE` [Delete user](https://developers.vtex.com/docs/api-reference/license-manager-api#delete-/api/license-manager/users/-userId-)

    - `POST` [Create user](https://developers.vtex.com/docs/api-reference/license-manager-api#post-/api/license-manager/users)

    - `GET` [Get list of users](https://developers.vtex.com/docs/api-reference/license-manager-api#get-/api/license-manager/site/pvt/logins/list/paged)


    ### Roles


    - `PUT` [Add roles to user or appKey](https://developers.vtex.com/docs/api-reference/license-manager-api#put-/api/license-manager/users/-userId-/roles)

    - `GET` [Get roles by user or appKey](https://developers.vtex.com/docs/api-reference/license-manager-api#get-/api/license-manager/users/-userId-/roles)

    - `DELETE` [Remove role from user or appKey](https://developers.vtex.com/docs/api-reference/license-manager-api#delete-/api/license-manager/users/-userId-/roles/-roleId-)

    - `GET` [Get list of roles](https://developers.vtex.com/docs/api-reference/license-manager-api#get-/api/license-manager/site/pvt/roles/list/paged)


    ### App Keys


    - `POST` [Create new appkey](https://developers.vtex.com/docs/api-reference/license-manager-api#post-/api/vlm/appkeys)

    - `GET` [Get appKeys from account](https://developers.vtex.com/docs/api-reference/license-manager-api#get-/api/vlm/appkeys)

    - `PUT` [Update appKey](https://developers.vtex.com/docs/api-reference/license-manager-api#put-/api/vlm/appkeys/-id-)


    ### Store


    - `GET` [Get stores](https://developers.vtex.com/docs/api-reference/license-manager-api#get-/api/vlm/account/stores)


    ### Account


    - `GET` [Get information about account](https://developers.vtex.com/docs/api-reference/license-manager-api#get-/api/vlm/account)'
  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
security:
- appKey: []
  appToken: []
- VtexIdclientAutCookie: []
tags:
- name: Users
paths:
  /api/license-manager/users/{userId}:
    get:
      tags:
      - Users
      summary: VTex Get user
      description: "Allows you to get a user from the database, using the `userId` as the identifier. \n\n## Permissions\n\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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| License Manager | Services access control | **Remove user** |\n| License Manager | Services access control | **Save user** |\n\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):\n\n| **Role** | **Resource** | \n| --------------- | ----------------- | \n| User Administrator - RESTRICTED | Save user |\n\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).\n\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      operationId: GetUser
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: userId
        in: path
        description: ID from queried user.
        required: true
        style: simple
        schema:
          type: string
          example: e845b52a40e24654a2c70766adb5762b
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: ID of the user.
                    type: string
                  name:
                    description: Name of the user.
                    type: string
                  email:
                    description: Email of the user.
                    type: string
              example:
                id: e845b52a40e24654a2c70766adb5762b
                name: Jane
                email: jane@mail.com
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  Message:
                    description: Error message.
                    type: string
              example:
                Message: Invalid UserId
        '405':
          description: Method Not Allowed - A null `userId` sends the request to a path that is not allowed.
      deprecated: false
    delete:
      tags:
      - Users
      summary: VTex Delete user
      description: "Allows you to delete a user from the database, using the `userId` as the identifier. \n\n## Permissions\n\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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| License Manager | Services access control | **Save user** |\n| License Manager | Services access control | **Remove user** |\n\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):\n\n| **Role** | **Resource** | \n| --------------- | ----------------- | \n| User Administrator - RESTRICTED | Save user |\n\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).\n\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: userId
        in: path
        description: ID from queried user.
        required: true
        style: simple
        schema:
          type: string
          example: e845b52a40e24654a2c70766adb5762b
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  Message:
                    description: Error message.
                    type: string
              example:
                Message: Invalid UserId
      deprecated: false
  /api/license-manager/users:
    post:
      tags:
      - Users
      summary: VTex Create user
      description: "Allows you to create a user by providing an email (mandatory) and name (optional). The email must be in a valid format. The success response will contain the generated `userId` for that user. \n\n## Permissions\n\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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| License Manager | Services access control | **Save user** |\n\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):\n\n| **Role** | **Resource** | \n| --------------- | ----------------- | \n| User Administrator - RESTRICTED | Save user |\n\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).\n\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      operationId: CreateUser
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            example:
              name: Jane
              email: jane@mail.com
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: ID of the user.
                    type: string
                  email:
                    description: Email of the user.
                    type: string
                  name:
                    description: Name of the user.
                    type: string
              example:
                id: a404870467d24533a085a6b3c6a5a320
                email: jane@mail.com
                name: Jane
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  Message:
                    type: string
                    description: Error message.
              example:
                Message: Invalid email
      deprecated: false
  /api/license-manager/site/pvt/logins/list/paged:
    get:
      tags:
      - Users
      summary: VTex Get list of users
      description: "Returns a list of registered users. The response is divided in pages. The query parameter `numItems` defines the number of items in each page, and consequently the amount of pages for the whole list. \n\n## Permissions\n\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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| License Manager | Services access control | **Get paged users** |\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.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/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."
      operationId: GetListUsers
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: numItems
        in: query
        description: Number of items in the returned page.
        required: false
        style: form
        schema:
          type: integer
          example: 10
      - name: pageNumber
        in: query
        description: Which page from the whole list will be returned.
        required: false
        style: form
        schema:
          type: integer
          example: 1
      - name: sort
        in: query
        description: Chooses the field that the list will be sorted by.
        required: false
        style: form
        schema:
          type: string
          example: name
      - name: sortType
        in: query
        description: Defines the sorting order. `ASC` is used for ascendant order. `DSC` is used for descendant order.
        required: false
        style: form
        schema:
          type: string
          example: ASC
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUsersResponse'
              example:
                items:
                - id: a404870467d24533a085a6b3c6a5a320
                  email: mynewuser@mydomain.com
                  isAdmin: false
                  isReliable: false
                  isBlocked: false
                  roles: []
                  accountNames: []
                  name: testuser
                paging:
                  page: 1
                  perPage: 1
                  total: 1
                  pages: 1
components:
  parameters:
    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
        default: application/json
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
  schemas:
    Paging:
      description: Paging object.
      required:
      - page
      - perPage
      - total
      - pages
      type: object
      properties:
        page:
          description: Current page number.
          type: integer
        perPage:
          description: Items per page.
          type: integer
        total:
          description: Total of items.
          type: integer
        pages:
          description: Total of pages.
          type: integer
    ListUsersResponse:
      description: Response body for listing all users.
      type: object
      properties:
        items:
          description: Array of user objects.
          type: array
          items:
            $ref: '#/components/schemas/UserItems'
        paging:
          $ref: '#/components/schemas/Paging'
    CreateUserRequest:
      description: Request body for creating users.
      required:
      - email
      type: object
      properties:
        name:
          description: Name of the user.
          type: string
          example: John
        email:
          description: Email of the user.
          type: string
          example: john@mail.com
    UserItems:
      description: Object with information about an user.
      type: object
      properties:
        id:
          description: ID of the user.
          type: string
        email:
          description: Email of the user.
          type: string
        isAdmin:
          description: Defines if the user has administrative access (`true`) or not (`false`).
          type: boolean
        isReliable:
          description: For internal use only.
          type: boolean
        isBlocked:
          description: Defines if the user is blocked (`true`) or not (`false`).
          type: boolean
        roles:
          type: array
          description: Array of user roles.
          items:
            type: string
            description: Role ID.
        accountNames:
          type: array
          description: Array of account names.
          items:
            type: string
            description: Account names.
        name:
          description: Name of the user.
          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.'