openapi: 3.0.1
info:
  title: User and Account API (Beta)
  description: API documentation for User and Account service
  version: 1.0.0_Beta
servers:
  - url: https://flexera1000-uat.flexnetoperations.com/users-accounts-api
    description: Generated server url
tags:
  - name: Account
    description: >-
      API for managing account-related operations such as creation, retrieval,
      update, and deletion.
  - name: User
    description: >-
      API for managing user-related operations such as creation, retrieval,
      update, and deletion.
paths:
  /v1/users:
    get:
      tags:
        - User
      summary: Get a list of users
      description: >-
        Returns a paginated list of users. Supports optional filters and sorting
        parameters to refine the results. Useful for displaying user
        information, managing users in FlexNet operations, or performing
        administrative tasks.
      operationId: getUsers
      parameters:
        - name: userName
          in: query
          description: Filter by user name
          required: false
          schema:
            type: string
        - name: displayName
          in: query
          description: Filter by display name
          required: false
          schema:
            type: string
        - name: email
          in: query
          description: Filter by user email
          required: false
          schema:
            type: string
        - name: accountId
          in: query
          description: Filter by account ID
          required: false
          schema:
            type: string
        - name: accountName
          in: query
          description: Filter by account name
          required: false
          schema:
            type: string
        - name: accountType
          in: query
          description: >-
            Filter by account type
            (HOME,PUBLISHER,CUSTOMER,SELF_REGISTERED,CHANNEL_PARTNER,UNKNOWN)
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Status of the user (active,inactive)
          required: false
          schema:
            type: string
        - name: sort_by
          in: query
          description: Field to sort by (displayName,email,status)
          required: false
          schema:
            type: string
        - name: sort_order
          in: query
          description: Order to sort by (asc/desc)
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: Requested page number
          required: false
          schema:
            type: integer
            format: int32
        - name: limit
          in: query
          description: Number of records per page
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Get user list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
    post:
      tags:
        - User
      summary: Create a user
      operationId: postUser
      requestBody:
        description: >-
          Mandatory fields: firstName, lastName, emailAddress, accountRoles
          [accountName, roles]
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
        required: true
      responses:
        '201':
          description: Created a user successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/account:
    post:
      tags:
        - Account
      summary: Create an account
      operationId: postAccount
      requestBody:
        description: 'Mandatory fields: accountId, name'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
        required: true
      responses:
        '201':
          description: Created an account successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Account id already exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/users/{userName}:
    get:
      tags:
        - User
      summary: Get a user
      operationId: getUsers_1
      parameters:
        - name: userName
          in: path
          description: User name of the user
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Get user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
  /v1/accounts:
    get:
      tags:
        - Account
      summary: Get accounts
      operationId: getAccountsByFilterAndPagination
      parameters:
        - name: accountId
          in: query
          description: Filter Accounts by Account ID
          required: false
          schema:
            type: string
        - name: accountName
          in: query
          description: Filter Accounts by Account Name
          required: false
          schema:
            type: string
        - name: accountType
          in: query
          description: Filter Accounts by Account type
          required: false
          schema:
            type: array
            items:
              type: string
            default:
              - CUSTOMER
        - name: rootAccountOnly
          in: query
          description: Filter root accounts only
          required: false
          schema:
            type: boolean
            default: false
        - name: page
          in: query
          description: Requested page number
          required: false
          schema:
            type: integer
            format: int32
        - name: limit
          in: query
          description: Number of records per page
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Get Accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
components:
  schemas:
    Attribute:
      type: object
      properties:
        name:
          type: string
          description: Name of the custom attribute
          example: REGION
        value:
          type: object
          description: >-
            Value assigned to the custom attribute. Format and example depend on
            the type: 

            - Single Text: "EMEA" 

            - Multi-valued text: provide list of values between brackets []
            delimited by , (e.g. ["Text1", "Text2"]) 

            - Date: "YYYY/MM/DD" (e.g. "2025/12/31") 

            - Number: 12345
          example: EMEA
      description: >-
        Represents user accounts custom attributes. Mandatory custom attributes
        must be provided for the request to be successful.
    User:
      required:
        - accountRoles
        - emailAddress
        - firstName
        - lastName
      type: object
      properties:
        firstName:
          type: string
          description: First Name of the user
          example: John
        lastName:
          type: string
          description: Last Name of the user
          example: Doe
        displayName:
          type: string
          description: Display name of the user
          example: John Doe
        emailAddress:
          maxLength: 1000
          minLength: 0
          type: string
          description: Email address of the user
          example: johndoe@xyz.com
        phoneNumber:
          type: string
          description: User’s phone number
          example: '989915487'
        faxNumber:
          type: string
          description: User’s fax number
          example: '01154785'
        street:
          type: string
          description: Street portion of address
          example: High Street
        city:
          type: string
          description: City portion of address
          example: New York
        state:
          type: string
          description: State portion of address
          example: The Empire State
        zipcode:
          type: string
          description: Postal code of address
          example: '10118'
        country:
          type: string
          description: Two-letter country code
          example: US
        locale:
          type: string
          description: User’s locale
          example: en_US
        portalLogin:
          type: boolean
          description: Whether the User requires portal login or not?
          example: true
        userName:
          type: string
          description: >-
            Important: The user name must match the email address for the user.
            If canLogin is set to false, this field is ignored. if canLogin is
            set to true, this field is required. 
          example: johndoe@xyz.com
        status:
          type: string
          description: >-
            Flag to indicate if the user should be Active or Inactive, Status
            can be one of the following values: Active, Inactive
          example: Active
        timezone:
          type: string
          description: >-
            Provide time zone setting in the format: GMT#.#DST#. When a user is
            saved, this offset is converted to a time zone string and the time
            zone string is displayed when a user is retrieved.
          example: GMT-6.0DST0
        shared:
          type: boolean
          description: Is this a shared login among several users?
          example: false
        accountRoles:
          maxItems: 2147483647
          minItems: 1
          type: array
          description: >-
            List of account associated with user. Set user's account and list of
            the user’s roles. User name and roles are required if the user can
            log in
          items:
            $ref: '#/components/schemas/UserAccountRole'
        attributes:
          type: array
          description: >-
            List of user custom attributes. Note that mandatory custom
            attributes must be included in this list
          items:
            $ref: '#/components/schemas/Attribute'
        optIn:
          type: boolean
          description: Whether the User should opt to receive email notifications
          example: false
        canLogin:
          type: boolean
          description: >-
            Indicates whether created user can login to portal or not. If
            canLogin is false, the user is treated as a contact.
          example: true
    UserAccountRole:
      required:
        - accountName
        - roles
      type: object
      properties:
        accountName:
          type: string
          description: >-
            Account Name [unique identifier of Account - short name] which needs
            to be linked to User
          example: '123456'
        expiryDate:
          type: string
          description: >-
            Expiry date of the user in YYYY-MM-DD format. Expiry date should be
            provided when canLogin flag is true.  It is the date when user is no
            longer linked to the account. If included, the value cannot be null.
            If not included, the user's access to the account will not expire. 
          example: '2025-12-30'
        roles:
          maxItems: 2147483647
          minItems: 1
          type: array
          description: List of roles.
          example:
            - USER
            - ADMIN
          items:
            type: string
            description: List of roles.
            example: '["USER","ADMIN"]'
      description: >-
        List of account associated with user. Set user's account and list of the
        user’s roles. User name and roles are required if the user can log in
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
    Response:
      type: object
      properties:
        status:
          type: string
    Account:
      required:
        - accountId
        - name
      type: object
      properties:
        accountId:
          type: string
          description: Unique identifier of the account (short account name)
          example: '12345'
        name:
          type: string
          description: Display name of the account (full account name)
          example: Flexera Software LLC
        description:
          type: string
          description: Description of the account
          example: Flexera Software LLC - Main Office
        address1:
          type: string
          description: First line of account's address
          example: 123 Flexera St
        address2:
          type: string
          description: Second line of account's address
          example: Suite 100
        city:
          type: string
          description: City portion of account's address
          example: Chicago
        state:
          type: string
          description: State portion of account's address
          example: IL
        zipcode:
          type: string
          description: Zip/Postal code of the account's address
          example: '60601'
        country:
          type: string
          description: Two-letter country code
          example: US
        region:
          type: string
          description: Region in which this account's address exists
          example: North America
        visible:
          type: boolean
          description: >-
            Applicable to CUSTOMER and CHANNEL_PARTNER accounts, visible
            determines whether or not an account unrelated to this account can
            see the name of this account when it is in a channel partner tier of
            an entitlement, line item, or device. If visible is false, this
            account will appear as Name Withheld to unrelated accounts. Default:
            true
          example: true
        accountType:
          type: string
          description: >-
            Defines the account type. Valid values: CUSTOMER, PUBLISHER,
            CHANNEL_PARTNER Default: CUSTOMER. (Using REST API, a new account
            cannot be created with an accountType of SELF_REGISTERED.)
          example: CUSTOMER
        attributes:
          type: array
          description: >-
            List of custom attributes attached to this account. Note that
            mandatory custom attributes must be included in this list
          items:
            $ref: '#/components/schemas/Attribute'
