VTEX Roles API

openapi: 3.2.0
info:
  title: VTex License Manager Roles 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: Roles
paths:
  /api/license-manager/users/{userId}/roles:
    put:
      tags:
      - Roles
      summary: VTex Add roles to user or appKey
      description: "Allows you to add License Manager [roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) to a particular user or application key by specifying the list of role IDs on the request body. \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: PutRolesinUser
      parameters:
      - name: userId
        in: path
        description: ID of the user.
        required: true
        style: simple
        schema:
          type: string
          example: a404870467d24533a085a6b3c6a5a320
      requestBody:
        description: List of role IDs to add to the user or application key.
        content:
          application/json:
            schema:
              type: array
              description: Array containing role IDs.
              items:
                type: integer
                format: int32
                description: Role ID, which 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.
                example: 9000
            example:
            - 9000
            - 9111
            - 9333
            - 9444
        required: true
      responses:
        '204':
          description: Success - A no-content response, but the roles were added successfully.
        '400':
          description: Bad Request - A userId or role list with invalid format. The message on the body of the response will contain further information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Message:
                    description: Error message.
                    type: string
              example:
                Message: Roles list contains roles that do not exist in this account
        '500':
          description: Unexpected error - One possible reason is that the userId is not present on the database.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Message:
                    type: string
                    description: Error message.
              example:
                Message: Unexpected error
      deprecated: false
    get:
      tags:
      - Roles
      summary: VTex Get roles by user or appKey
      description: "Retrieves License Manager [roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) of a particular user or application key. \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: GetRolesbyUser
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: userId
        in: path
        description: ID of the user.
        required: true
        style: simple
        schema:
          type: string
          example: e845b52a40e24654a2c70766adb5762b
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                description: Array of role objects.
                items:
                  type: object
                  description: Object with information about each role.
                  properties:
                    id:
                      description: ID of role.
                      type: integer
                      format: int32
                    name:
                      description: Name of the role.
                      type: string
              example:
              - id: 957
                name: Call center operator
              - id: 1
                name: Owner (Admin Super)
      deprecated: false
  /api/license-manager/users/{userId}/roles/{roleId}:
    delete:
      tags:
      - Roles
      summary: VTex Remove role from user or appKey
      description: "Allows you to remove a License Manager [role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) from a specific user or application key. This method only allows the removal of one role per request. The role's ID must be specified on the request path, not on the request body.\n\n> Note that a successful response returns a `204` response with an empty body. A deletion on a role or user that does not exist will also return a `204`. Thus, this method should not be used to verify the existence of a specific user or role. \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: RemoveRolefromUser
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: userId
        in: path
        description: ID of the user.
        required: true
        style: simple
        schema:
          type: string
          example: e845b52a40e24654a2c70766adb5762b
      - name: roleId
        in: path
        description: ID of the role which will be removed from the user.
        required: true
        style: simple
        schema:
          type: string
          example: '1'
      responses:
        '204':
          description: Success - A no-content response, but the role deletion was performed successfully.
        '400':
          description: Bad Request - A userId or role list with invalid format. The message on the body of the response will contain further information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Message:
                    type: string
                    description: Error message.
              example:
                Message: Invalid UserId
        '405':
          description: Method Not Allowed
      deprecated: false
  /api/license-manager/site/pvt/roles/list/paged:
    get:
      tags:
      - Roles
      summary: VTex Get list of roles
      description: "Returns a list of License Manager [roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc). 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 roles** |\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: GetListRoles
      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: id
      - 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
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRolesResponse'
              example:
                items:
                - id: 957
                  isAdmin: false
                  roleType: 0
                  products:
                  - id: null
                    categoryId: null
                    categoryName: null
                    description: null
                    consoleUrlMask: null
                    urlConfiguration: null
                    webApiUrlMask: null
                    url: null
                    productResources: null
                    name: Catalog
                  - id: null
                    categoryId: null
                    categoryName: null
                    description: null
                    consoleUrlMask: null
                    urlConfiguration: null
                    webApiUrlMask: null
                    url: null
                    productResources: null
                    name: OMS
                  resources: null
                  logins: null
                  name: Call center operator
                paging:
                  page: 1
                  perPage: 1
                  total: 1
                  pages: 1
components:
  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
    ProductItems:
      description: Object representing License Manager products.
      type: object
      properties:
        id:
          deprecated: true
          description: License Manager product ID.
          type:
          - string
          - 'null'
        categoryId:
          deprecated: true
          description: Category ID.
          type:
          - string
          - 'null'
        categoryName:
          deprecated: true
          type:
          - string
          - 'null'
          description: Category name.
        description:
          deprecated: true
          type:
          - string
          - 'null'
          description: Description.
        consoleUrlMask:
          deprecated: true
          type:
          - string
          - 'null'
          description: Console URL mask.
        urlConfiguration:
          deprecated: true
          type:
          - string
          - 'null'
          description: URL configuration.
        webApiUrlMask:
          deprecated: true
          type:
          - string
          - 'null'
          description: Web API mask.
        url:
          deprecated: true
          type:
          - string
          - 'null'
          description: URL.
        productResources:
          deprecated: true
          type:
          - string
          - 'null'
          description: Product resources.
        name:
          description: Name of the License Manager product.
          type: string
    RoleItems:
      description: Object with information about a role.
      type: object
      properties:
        id:
          description: ID of the role.
          type: integer
        isAdmin:
          description: Defines if the role has administrative access (`true`) or not (`false`).
          type: boolean
        roleType:
          description: Returns `1` for custom roles, and `0` for predefined roles.
          type: integer
        products:
          type: array
          description: Array of License Manager product objects.
          items:
            $ref: '#/components/schemas/ProductItems'
        resources:
          type:
          - string
          - 'null'
          description: Resources.
          deprecated: true
        logins:
          type:
          - string
          - 'null'
          description: Logins.
          deprecated: true
        name:
          description: Name of the role.
          type: string
    ListRolesResponse:
      description: Response body for listing all roles.
      type: object
      properties:
        items:
          description: Array of role objects.
          type: array
          items:
            $ref: '#/components/schemas/RoleItems'
        paging:
          $ref: '#/components/schemas/Paging'
  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
  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.'