openapi: 3.1.0
info:
  title: Automation Anywhere API Task Execution AccessDetails Authentication API
  description: The Automation Anywhere API Task Execution API enables developers to invoke API Tasks — a specialized type of cloud-based bot designed to be called synchronously from external applications like a REST service. The API provides endpoints to list API Task allocations, generate unique execution URLs and tokens, and execute API Tasks in real time. API Tasks execute on cloud infrastructure without requiring local Bot Runner devices, and are designed for low latency with near-real-time response rates. The execution URL and authorization token are short-lived and must be refreshed periodically to prevent authorization failures.
  version: '2019'
  contact:
    name: Automation Anywhere Support
    url: https://support.automationanywhere.com
  termsOfService: https://www.automationanywhere.com/terms-of-service
servers:
- url: https://{controlRoomUrl}/orchestrator/v1/hotbot
  description: Automation Anywhere API Task Orchestrator
  variables:
    controlRoomUrl:
      default: your-control-room.automationanywhere.com
      description: Your Control Room hostname
security:
- bearerAuth: []
- xAuthorization: []
tags:
- name: Authentication
  description: Generate, refresh, validate, and revoke JWT tokens for API access
paths:
  /v2/authentication:
    post:
      operationId: authenticate
      summary: Authenticate and generate JWT
      description: Authenticates a Control Room user using username and password or username and API key, and returns a JSON Web Token (JWT) for use in subsequent API calls. The token is valid for 20 minutes by default and must be included in the X-Authorization or Authorization header of all subsequent requests.
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationRequest'
      responses:
        '200':
          description: Authentication successful, JWT returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/authentication/token:
    get:
      operationId: validateToken
      summary: Validate a JWT token
      description: Verifies whether the provided JWT token is currently valid. Returns a boolean indicating validity. The token can be passed via the X-Authorization header or as a query parameter (deprecated).
      tags:
      - Authentication
      parameters:
      - $ref: '#/components/parameters/TokenQueryParam'
      responses:
        '200':
          description: Token validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenValidationResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/authentication/logout:
    post:
      operationId: logout
      summary: Logout and invalidate JWT
      description: Immediately invalidates the current JWT token, logging the user out of the Control Room API session. After calling this endpoint, the token can no longer be used for authenticated requests.
      tags:
      - Authentication
      responses:
        '204':
          description: Logout successful, token invalidated
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    UserSummary:
      type: object
      description: Abbreviated user object returned within authentication responses
      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
        roles:
          type: array
          description: Roles assigned to the user
          items:
            $ref: '#/components/schemas/RoleRef'
    AuthenticationResponse:
      type: object
      description: Response containing the JWT token for authenticated API access
      properties:
        token:
          type: string
          description: JWT token string to include in subsequent API request headers
        user:
          $ref: '#/components/schemas/UserSummary'
    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
    AuthenticationRequest:
      type: object
      description: Credentials for authenticating a Control Room user. Provide either password or apiKey along with the username.
      required:
      - username
      properties:
        username:
          type: string
          description: The Control Room username
        password:
          type: string
          description: The user's password (use instead of apiKey for password-based auth)
        apiKey:
          type: string
          description: The user's API key (use instead of password for key-based auth)
        multipleLogin:
          type: boolean
          description: Whether to allow multiple concurrent sessions for this user
    TokenValidationResponse:
      type: object
      description: Result of a token validity check
      properties:
        valid:
          type: boolean
          description: Whether the provided token is currently valid
    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
  parameters:
    TokenQueryParam:
      name: token
      in: query
      required: false
      description: JWT token to validate (deprecated; use X-Authorization header instead)
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the Authentication API
    xAuthorization:
      type: apiKey
      in: header
      name: X-Authorization
      description: JWT token obtained from the Authentication API
externalDocs:
  description: Automation Anywhere API Task Documentation
  url: https://docs.automationanywhere.com/bundle/enterprise-v2019/page/api-task-real-time-endpoint.html