openapi: 3.2.0
info:
  title: User Permission Management User Groups API
  description: 'This set of APIs allows managing user groups and associating users to the user groups. These user groups grant granular user permissions across Basware applications. The permissions granted by the user groups are managed in Basware Admin application.


    Each of the managed applications needs to support permission management through cross application user groups and be configured to have cross application user groups enabled. Supported applications include AP Automation, SmartPDF and Vault.'
  version: v1
servers:
- url: ''
security:
- Bearer: []
- oauth2authentication: []
tags:
- name: User Groups
paths:
  /v1/userGroups/{externalCode}:
    get:
      tags:
      - User Groups
      summary: Returns user group by externalCode
      parameters:
      - name: externalCode
        in: path
        description: The ExternalCode of the entity to be fetched
        required: true
        schema:
          type: string
      - name: x-amz-meta-continuationToken
        in: header
        description: Used to get next page of results when item count indicated by 'pageSize' is exceeded. A token is returned in header (not body) parameter 'X-amz-meta-continuationToken' of the response whenever there are more records to fetch. Post the received value here in a new HEADER parameter on the next GET request to receive the next page of results. When getting the next page of results, you must include the same query parameters that were used when getting the first page.
        schema:
          type: string
        example: 7a71f046-4450-47b1-9ee9-8af480f5be1b
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroup'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroup'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroup'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      operationId: getV1UserGroupsByExternalCode
      x-operation-id-source: derived
  /v1/userGroups:
    get:
      tags:
      - User Groups
      summary: Returns a list of available user groups
      parameters:
      - name: OrganizationExternalCode
        in: query
        schema:
          type: string
      - name: x-amz-meta-continuationToken
        in: header
        description: Used to get next page of results when item count indicated by 'pageSize' is exceeded. A token is returned in header (not body) parameter 'X-amz-meta-continuationToken' of the response whenever there are more records to fetch. Post the received value here in a new HEADER parameter on the next GET request to receive the next page of results. When getting the next page of results, you must include the same query parameters that were used when getting the first page.
        schema:
          type: string
        example: 4ef57cfb-145c-4e44-9337-ff363180c1c1
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroup'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroup'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroup'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      operationId: getV1UserGroups
      x-operation-id-source: derived
    post:
      tags:
      - User Groups
      summary: Create or update user group
      parameters:
      - name: Content-Type
        in: header
        description: Specifies the media type of the resource. Value application/json is supported.
        schema:
          type: string
        example: application/json
      requestBody:
        description: The user groups to create or update.
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UserGroup'
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UserGroup'
          text/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UserGroup'
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UserGroup'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroup'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroup'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroup'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/IModelValidationResult'
            application/json:
              schema:
                $ref: '#/components/schemas/IModelValidationResult'
            text/json:
              schema:
                $ref: '#/components/schemas/IModelValidationResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      operationId: postV1UserGroups
      x-operation-id-source: derived
    delete:
      tags:
      - User Groups
      summary: Delete user groups
      description: 'For manual one-time operations only, such as a manual clean-up to remove test data generated during API integration development. Only removes records from API layer.

        Deletion in target systems needs to be done separately using the data deletion mechanisms available in each of the target system in addition to deleting the data in Basware API.'
      requestBody:
        description: "Contains the body of the request.\n            Either externalCode or lastUpdated -field is required. If both values are provided, externalCode will have the priority."
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/DeleteDataRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteDataRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/DeleteDataRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/DeleteDataRequest'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '400':
          description: BadRequest
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/IModelValidationResult'
            application/json:
              schema:
                $ref: '#/components/schemas/IModelValidationResult'
            text/json:
              schema:
                $ref: '#/components/schemas/IModelValidationResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '202':
          description: RequestAccepted
        '500':
          description: Unexpected error
      operationId: deleteV1UserGroups
      x-operation-id-source: derived
components:
  schemas:
    IModelValidationResult:
      type: object
      properties:
        requestId:
          type:
          - string
          - 'null'
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/IModelValidationError'
          readOnly: true
        hasErrors:
          type: boolean
          readOnly: true
      additionalProperties: false
    UserGroup:
      required:
      - externalCode
      - name
      - organizationExternalCode
      type: object
      properties:
        externalCode:
          maxLength: 100
          minLength: 1
          type: string
          description: Unique identifier for the user group. Used to identify the user group when it is updated.
          example: IND_Admins
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Name of the user group
          example: India Admins
        description:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Description of the user group
          example: Group for India admin users
        organizationExternalCode:
          maxLength: 100
          minLength: 1
          type: string
          description: ExternalCode identifier for the organization on which the user group resides.
          example: BW10
      additionalProperties: false
      description: 'Represents a user group within an organization, including its unique identifier,

        name, description, and associated organization information.'
    BulkOperationStatus:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      type: integer
      description: Represents the possible statuses of a bulk operation.
      format: int32
    DeleteDataRequest:
      type: object
      properties:
        externalCode:
          maxLength: 36
          minLength: 0
          type:
          - string
          - 'null'
          description: Single item can be deleted using externalCode and final status is returned immediately.
        lastUpdated:
          type:
          - string
          - 'null'
          description: 'To delete records updated after specific time, use lastUpdated -field. This will delete all items that have been updated after the specified date. In response, user will get the taskStatus api link where the task status can be checked. Note: ''0001-01-01'' can be used to delete all records.'
          format: date-time
      additionalProperties: false
    IModelValidationError:
      type: object
      properties:
        code:
          type:
          - string
          - 'null'
        externalCode:
          type:
          - string
          - 'null'
        info:
          type:
          - string
          - 'null'
        message:
          type:
          - string
          - 'null'
        type:
          type:
          - string
          - 'null'
        cdmErrorMappingOrganizationCode:
          type:
          - string
          - 'null'
      additionalProperties: false
    DeleteResponse:
      type: object
      properties:
        statusApiLink:
          type:
          - string
          - 'null'
          description: Gets or sets the API link to check the status of the delete operation.
        taskName:
          type:
          - string
          - 'null'
          description: Gets or sets the name of the delete task.
        taskStatus:
          type:
          - string
          - 'null'
          description: Gets or sets the current status of the delete task.
          readOnly: true
        statusEnum:
          $ref: '#/components/schemas/BulkOperationStatus'
      additionalProperties: false
      description: Represents the response returned after a delete operation.
  securitySchemes:
    Bearer:
      type: http
      description: Please insert basic authentication credentials into fields
      scheme: basic
    oauth2authentication:
      type: oauth2
      description: OAuth2 client credentials flow.
      flows:
        clientCredentials:
          tokenUrl: https://api.basware.com/v1/tokens
          scopes:
            userGroups.read: GET user groups
            userGroups.write: POST user groups
            userGroups.delete: DELETE user groups
            userGroupAssociatedUsers.read: GET user associations with user group
            userGroupAssociatedUsers.write: POST user associations to user group
            userGroupAssociatedUsers.delete: DELETE user associations from user group