automation-anywhere Roles API

openapi: 3.2.0
info:
  title: Automation Anywhere Control Room Roles 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: Roles
  description: Create, list, retrieve, update, and delete user roles
paths:
  /v2/usermanagement/roles:
    post:
      operationId: createRole
      summary: Create a role
      description: Creates a new role in the Control Room with the specified name, description, and set of permissions. Roles are used to grant users access to specific features, folders, and API operations.
      tags:
      - Roles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoleRequest'
      responses:
        '201':
          description: Role created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
        '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/roles/list:
    post:
      operationId: listRoles
      summary: List roles
      description: Retrieves a paginated, filterable list of Control Room roles. Supports filtering by name and other attributes. Returns role metadata including permissions and member counts.
      tags:
      - Roles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterRequest'
      responses:
        '200':
          description: List of roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleListResponse'
        '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/roles/{id}:
    get:
      operationId: getRole
      summary: Get role by ID
      description: Retrieves detailed information about a specific role, including its name, description, permissions, and the list of users assigned to it.
      tags:
      - Roles
      parameters:
      - $ref: '#/components/parameters/RoleIdParam'
      responses:
        '200':
          description: Role details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateRole
      summary: Update a role
      description: Updates an existing role's name, description, and permission set. Changes apply immediately to all users assigned to the role.
      tags:
      - Roles
      parameters:
      - $ref: '#/components/parameters/RoleIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoleRequest'
      responses:
        '201':
          description: Role updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
        '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: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteRole
      summary: Delete a role
      description: Permanently deletes a Control Room role. Users assigned only to this role will lose associated permissions. System roles (AAE_Admin, AAE_Basic) cannot be deleted.
      tags:
      - Roles
      parameters:
      - $ref: '#/components/parameters/RoleIdParam'
      responses:
        '204':
          description: Role deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RoleResponse:
      type: object
      description: Full role record returned from create, read, or update operations
      properties:
        id:
          type: integer
          format: int64
          description: Unique numeric identifier of the role
        name:
          type: string
          description: Role name
        description:
          type: string
          description: Role description
        permissions:
          type: array
          description: Permissions granted by this role
          items:
            $ref: '#/components/schemas/Permission'
        createdBy:
          type: integer
          format: int64
          description: ID of the user who created the role
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the role was created
        updatedBy:
          type: integer
          format: int64
          description: ID of the user who last modified the role
        updatedOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update
    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'
    UpdateRoleRequest:
      type: object
      description: Payload to update an existing Control Room role
      properties:
        name:
          type: string
          description: Updated name for the role
        description:
          type: string
          description: Updated description of the role's purpose
        permissions:
          type: array
          description: Updated set of permissions; replaces existing permissions
          items:
            $ref: '#/components/schemas/Permission'
    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
    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
    RoleListResponse:
      type: object
      description: Paginated list of role records
      properties:
        list:
          type: array
          description: Array of role records matching the filter criteria
          items:
            $ref: '#/components/schemas/RoleResponse'
        page:
          $ref: '#/components/schemas/PageInfo'
    Permission:
      type: object
      description: A single permission entry granting access to a specific feature or resource
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the permission
        action:
          type: string
          description: The action permitted (e.g., view, create, run, edit, delete)
        resourceType:
          type: string
          description: The type of resource this permission applies to
        resourceId:
          type: integer
          format: int64
          description: Specific resource ID if this is a resource-scoped permission
    CreateRoleRequest:
      type: object
      description: Payload to create a new Control Room role
      required:
      - name
      properties:
        name:
          type: string
          description: Unique name for the new role
        description:
          type: string
          description: Human-readable description of the role's purpose
        permissions:
          type: array
          description: List of permission objects granting access to features
          items:
            $ref: '#/components/schemas/Permission'
    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:
    RoleIdParam:
      name: id
      in: path
      required: true
      description: Unique numeric identifier of the role
      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