automation-anywhere Users API

openapi: 3.2.0
info:
  title: Automation Anywhere Control Room Users API
  description: The Automation Anywhere Control Room API is a comprehensive set of RESTful APIs that enable programmatic management and administration of the Automation 360 RPA platform.
  version: '2019'
  contact:
    name: Automation Anywhere Support
    url: https://support.automationanywhere.com
  termsOfService: https://www.automationanywhere.com/terms-of-service
servers:
- url: https://{controlRoomUrl}
  description: Automation Anywhere Control Room Instance
  variables:
    controlRoomUrl:
      default: your-control-room.automationanywhere.com
      description: Your Control Room hostname
security:
- bearerAuth: []
- xAuthorization: []
tags:
- name: Users
  description: Create, list, retrieve, update, and delete Control Room users
paths:
  /v2/usermanagement/users:
    post:
      operationId: createUser
      summary: Create a user
      description: Creates a new user in the Control Room with the specified username, email, roles, and other attributes. The caller must have the AAE_Admin or user management permissions to invoke this endpoint.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/usermanagement/users/list:
    post:
      operationId: listUsers
      summary: List users
      description: Retrieves a paginated, filterable list of Control Room users. Supports filtering by username, email, role, and other attributes. The response includes user metadata and assigned roles.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterRequest'
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/usermanagement/users/{uid}:
    get:
      operationId: getUser
      summary: Get user by ID
      description: Retrieves detailed information about a specific Control Room user, including their roles, permissions, license assignments, and account status.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateUser
      summary: Update a user
      description: Updates an existing Control Room user's attributes including email, roles, license type, and enabled/disabled status. Replaces the full user record with the provided values.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteUser
      summary: Delete a user
      description: Permanently deletes a Control Room user account. This action cannot be undone. All automations associated with the user's private workspace may need to be recovered separately using the repository recovery API.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      responses:
        '204':
          description: User deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    UpdateUserRequest:
      type: object
      description: Payload to update an existing Control Room user account
      properties:
        email:
          type: string
          format: email
          description: Updated email address for the user
        firstName:
          type: string
          description: Updated first name
        lastName:
          type: string
          description: Updated last name
        roles:
          type: array
          description: Updated list of role assignments; replaces existing assignments
          items:
            $ref: '#/components/schemas/RoleRef'
        licenseFeatures:
          type: array
          description: Updated license feature types
          items:
            type: string
        enabled:
          type: boolean
          description: Whether the user account is active
        password:
          type: string
          description: New password for the user
    PageInfo:
      type: object
      description: Pagination metadata returned with list responses
      properties:
        offset:
          type: integer
          description: Starting index of the returned results
        total:
          type: integer
          description: Total number of records matching the query
        totalFilter:
          type: integer
          description: Total number of records after filters are applied
    PageRequest:
      type: object
      description: Pagination parameters for list requests
      properties:
        offset:
          type: integer
          description: Zero-based starting index of the result page
          minimum: 0
        length:
          type: integer
          description: Maximum number of results to return per page
          minimum: 1
          maximum: 1000
    FilterExpression:
      type: object
      description: Logical filter expression for querying resources
      properties:
        operator:
          type: string
          description: Logical operator combining child filters (and, or, not)
          enum:
          - and
          - or
          - not
          - eq
          - ne
          - lt
          - le
          - gt
          - ge
          - substring
          - startswith
        operands:
          type: array
          description: Child filter expressions or field/value pairs
          items:
            $ref: '#/components/schemas/FilterOperand'
    UserResponse:
      type: object
      description: Full user record returned from create, read, or update operations
      properties:
        id:
          type: integer
          format: int64
          description: Unique numeric identifier of the user
        username:
          type: string
          description: The user's login username
        email:
          type: string
          format: email
          description: The user's email address
        firstName:
          type: string
          description: User's first name
        lastName:
          type: string
          description: User's last name
        roles:
          type: array
          description: Roles assigned to the user
          items:
            $ref: '#/components/schemas/RoleRef'
        licenseFeatures:
          type: array
          description: License features assigned to the user
          items:
            type: string
        enabled:
          type: boolean
          description: Whether the user account is currently active
        createdBy:
          type: integer
          format: int64
          description: ID of the user who created this account
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the user was created
        updatedBy:
          type: integer
          format: int64
          description: ID of the user who last updated this account
        updatedOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update
    CreateUserRequest:
      type: object
      description: Payload to create a new Control Room user account
      required:
      - username
      - email
      - password
      properties:
        username:
          type: string
          description: Unique username for the new user
        email:
          type: string
          format: email
          description: Email address associated with the user account
        password:
          type: string
          description: Initial password for the user (not required for SSO-only users)
        firstName:
          type: string
          description: User's first name
        lastName:
          type: string
          description: User's last name
        roles:
          type: array
          description: List of role IDs to assign to the user
          items:
            $ref: '#/components/schemas/RoleRef'
        licenseFeatures:
          type: array
          description: License feature types assigned to the user (e.g., ATTENDED, UNATTENDED)
          items:
            type: string
        enabled:
          type: boolean
          description: Whether the user account is active and can log in
    Error:
      type: object
      description: Standard error response returned when an API request fails
      properties:
        code:
          type: string
          description: Error code identifying the error type
        message:
          type: string
          description: Human-readable description of the error
        details:
          type: array
          description: Additional error context or field-level validation errors
          items:
            type: string
    UserListResponse:
      type: object
      description: Paginated list of user records
      properties:
        list:
          type: array
          description: Array of user records matching the filter criteria
          items:
            $ref: '#/components/schemas/UserResponse'
        page:
          $ref: '#/components/schemas/PageInfo'
    RoleRef:
      type: object
      description: Reference to a role by its numeric ID
      properties:
        id:
          type: integer
          format: int64
          description: Numeric identifier of the referenced role
        name:
          type: string
          description: Name of the referenced role
    SortCriteria:
      type: object
      description: Sorting direction and field for list results
      properties:
        field:
          type: string
          description: Field name to sort by
        direction:
          type: string
          description: Sort direction
          enum:
          - asc
          - desc
    FilterOperand:
      type: object
      description: A single operand in a filter expression, either a field reference or a nested expression
      properties:
        field:
          type: string
          description: Field name to filter on
        value:
          type: string
          description: Value to compare against
    FilterRequest:
      type: object
      description: Generic filtering, pagination, and sorting request body used across list endpoints throughout the Control Room API.
      properties:
        filter:
          $ref: '#/components/schemas/FilterExpression'
        fields:
          type: array
          description: List of field names to include in the response
          items:
            type: string
        sort:
          type: array
          description: Sorting criteria for the result set
          items:
            $ref: '#/components/schemas/SortCriteria'
        page:
          $ref: '#/components/schemas/PageRequest'
  parameters:
    UserIdParam:
      name: uid
      in: path
      required: true
      description: Unique numeric identifier of the user
      schema:
        type: integer
        format: int64
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the Authentication API, passed as Authorization Bearer header
    xAuthorization:
      type: apiKey
      in: header
      name: X-Authorization
      description: JWT token obtained from the Authentication API, passed as X-Authorization header
externalDocs:
  description: Automation Anywhere Control Room API Documentation
  url: https://docs.automationanywhere.com/bundle/enterprise-v2019/page/enterprise-cloud/topics/control-room/control-room-api/cloud-control-room-apis.html