Automation Anywhere Credential Vault API

openapi: 3.1.0
info:
  title: Automation Anywhere Credential Vault API
  description: >-
    The Automation Anywhere Credential Vault API provides programmatic access
    to the Control Room's centralized secrets management system. It supports
    creating, reading, updating, and deleting credentials, credential attributes,
    Lockers, and Locker Keys used by bots during execution. Credentials stored
    in the Vault are encrypted and access-controlled through role-based
    permissions, ensuring bots can retrieve sensitive values such as passwords
    and API keys without exposing them in automation scripts. This API is used
    by administrators to provision and manage bot credentials as part of
    enterprise security and governance workflows. The API also supports managing
    the Credential Vault encryption key pair and operational mode.
  version: '2019'
  contact:
    name: Automation Anywhere Support
    url: https://support.automationanywhere.com
  termsOfService: https://www.automationanywhere.com/terms-of-service
externalDocs:
  description: Automation Anywhere Credential Vault API Documentation
  url: https://docs.automationanywhere.com/bundle/enterprise-v2019/page/cv-api-supported.html
servers:
  - url: https://{controlRoomUrl}/v2/credentialvault
    description: Automation Anywhere Control Room Credential Vault API v2
    variables:
      controlRoomUrl:
        default: your-control-room.automationanywhere.com
        description: Your Control Room hostname
tags:
  - name: AttributeValues
    description: Manage credential attribute values for individual credentials
  - name: Credentials
    description: Create, retrieve, update, delete, and search credentials
  - name: LockerConsumers
    description: Manage roles with consumer access to locker credentials
  - name: LockerMembers
    description: Manage user membership within lockers
  - name: Lockers
    description: Create, retrieve, update, and delete credential lockers
security:
  - bearerAuth: []
  - xAuthorization: []
paths:
  /credentials:
    post:
      operationId: createCredential
      summary: Create a credential
      description: >-
        Creates a new credential in the Credential Vault. A credential
        consists of a name, optional description, and one or more typed
        attributes (such as username and password fields). Once created,
        credentials must be added to a Locker to be accessible by bots.
      tags:
        - Credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialPost'
      responses:
        '200':
          description: Credential created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credentials/list:
    post:
      operationId: listCredentials
      summary: Search credentials
      description: >-
        Searches for credentials where the authenticated user is the owner
        or has access through a Locker. Supports filtering, sorting, and
        pagination. Only credential metadata is returned; attribute values
        are not included in list responses.
      tags:
        - Credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterRequest'
      responses:
        '200':
          description: Filtered list of credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialFilterResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credentials/{id}:
    get:
      operationId: getCredential
      summary: Get a credential by ID
      description: >-
        Retrieves a specific credential by its numeric ID, including its
        attributes and current values if the caller has access. The consumed
        query parameter controls whether to return attribute values intended
        for bot consumption.
      tags:
        - Credentials
      parameters:
        - $ref: '#/components/parameters/CredentialIdParam'
        - $ref: '#/components/parameters/ConsumedParam'
      responses:
        '200':
          description: Credential details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateCredential
      summary: Update a credential
      description: >-
        Updates an existing credential's name, description, or attributes.
        The caller must be the credential owner or have admin permissions.
        All attributes must be included in the request; omitted attributes
        will be removed.
      tags:
        - Credentials
      parameters:
        - $ref: '#/components/parameters/CredentialIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Credential'
      responses:
        '200':
          description: Credential updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '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: Credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteCredential
      summary: Delete a credential
      description: >-
        Permanently deletes a credential and all its associated attribute
        values from the Credential Vault. The credential must first be
        removed from any Lockers before it can be deleted.
      tags:
        - Credentials
      parameters:
        - $ref: '#/components/parameters/CredentialIdParam'
      responses:
        '200':
          description: Credential deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credentials/{id}/owner/{credentialOwnerId}:
    put:
      operationId: updateCredentialOwner
      summary: Update credential ownership
      description: >-
        Transfers ownership of a credential to another user. The new owner
        gains full administrative control over the credential including
        the ability to update, delete, and manage locker assignments.
      tags:
        - Credentials
      parameters:
        - $ref: '#/components/parameters/CredentialIdParam'
        - name: credentialOwnerId
          in: path
          required: true
          description: Numeric ID of the user who will become the new credential owner
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Credential ownership updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '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: Credential or new owner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credentials/{id}/attributevalues:
    get:
      operationId: listCredentialAttributeValues
      summary: List credential attribute values
      description: >-
        Retrieves all attribute values for a specific credential. Returns
        the current values of each attribute defined on the credential.
        The credentialAttributeId, userId, and encryptionKey query parameters
        can be used to filter the returned attribute values.
      tags:
        - AttributeValues
      parameters:
        - $ref: '#/components/parameters/CredentialIdParam'
        - $ref: '#/components/parameters/CredentialAttributeIdParam'
        - $ref: '#/components/parameters/UserIdQueryParam'
        - $ref: '#/components/parameters/EncryptionKeyParam'
      responses:
        '200':
          description: List of attribute values for the credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialAttributeValueList'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createCredentialAttributeValues
      summary: Create credential attribute values
      description: >-
        Sets or creates new attribute values for a specific credential.
        Attribute values are the actual secret data (e.g., passwords) stored
        against credential attribute definitions. Values are encrypted at
        rest using the Credential Vault key pair.
      tags:
        - AttributeValues
      parameters:
        - $ref: '#/components/parameters/CredentialIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialAttributeValuePostList'
      responses:
        '200':
          description: Attribute values created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialAttributeValueList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credentials/{id}/attributevalues/{attributeValueId}:
    put:
      operationId: updateCredentialAttributeValue
      summary: Update a credential attribute value
      description: >-
        Updates the value of a specific attribute on a credential. Used
        to rotate passwords, API keys, or other secrets without changing
        the credential's structure. The new value is encrypted and stored
        securely.
      tags:
        - AttributeValues
      parameters:
        - $ref: '#/components/parameters/CredentialIdParam'
        - $ref: '#/components/parameters/AttributeValueIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialAttributeValuePut'
      responses:
        '200':
          description: Attribute value updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialAttributeValue'
        '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: Credential or attribute value not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteCredentialAttributeValue
      summary: Delete a credential attribute value
      description: >-
        Removes a specific attribute value from a credential. After deletion,
        the attribute definition remains but the stored value is permanently
        removed from the Credential Vault.
      tags:
        - AttributeValues
      parameters:
        - $ref: '#/components/parameters/CredentialIdParam'
        - $ref: '#/components/parameters/AttributeValueIdParam'
      responses:
        '200':
          description: Attribute value deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Credential or attribute value not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lockers:
    post:
      operationId: createLocker
      summary: Create a locker
      description: >-
        Creates a new Locker in the Credential Vault. A Locker is a
        permission-controlled container that groups credentials and controls
        which roles (consumers) can use the credentials within it during
        bot execution. Lockers are the primary access control mechanism
        for the Credential Vault.
      tags:
        - Lockers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockerPost'
      responses:
        '200':
          description: Locker created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Locker'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lockers/list:
    post:
      operationId: listLockers
      summary: Search lockers
      description: >-
        Searches for Lockers that the authenticated user has access to.
        Returns paginated results with locker metadata. Supports filtering
        by name and other attributes.
      tags:
        - Lockers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterRequest'
      responses:
        '200':
          description: Filtered list of lockers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockerListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lockers/{id}:
    get:
      operationId: getLocker
      summary: Get a locker by ID
      description: >-
        Retrieves a specific Locker by its numeric ID, including its name,
        description, and configuration. Does not include the list of contained
        credentials; use the locker credentials endpoint for that.
      tags:
        - Lockers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
      responses:
        '200':
          description: Locker details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Locker'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Locker not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateLocker
      summary: Update a locker
      description: >-
        Updates an existing Locker's name and description. The caller must
        have Locker owner permissions to update its details.
      tags:
        - Lockers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockerPost'
      responses:
        '200':
          description: Locker updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Locker'
        '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: Locker not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteLocker
      summary: Delete a locker
      description: >-
        Permanently deletes a Locker. All credential associations within
        the Locker are removed. The credentials themselves are not deleted;
        they remain in the Credential Vault but lose Locker-based access.
      tags:
        - Lockers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
      responses:
        '200':
          description: Locker deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Locker not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lockers/{id}/credentials:
    get:
      operationId: listLockerCredentials
      summary: Get locker credentials
      description: >-
        Retrieves the list of credentials contained within a specific Locker.
        Returns credential metadata and the attributes available for bot
        consumption via the Locker's consumer roles.
      tags:
        - Lockers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
      responses:
        '200':
          description: List of credentials in the locker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockerCredentialList'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Locker not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lockers/{id}/credentials/{credentialId}:
    put:
      operationId: updateLockerCredential
      summary: Update a credential in a locker
      description: >-
        Updates the association or configuration of a credential within a
        Locker. Used to modify which credential attributes are exposed to
        consumer roles through this Locker.
      tags:
        - Lockers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
        - $ref: '#/components/parameters/CredentialIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockerCredentialUpdate'
      responses:
        '200':
          description: Locker credential updated successfully
        '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: Locker or credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: removeLockerCredential
      summary: Remove a credential from a locker
      description: >-
        Removes a credential from a Locker, revoking consumer role access
        to that credential through this Locker. The credential itself
        remains in the Credential Vault.
      tags:
        - Lockers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
        - $ref: '#/components/parameters/CredentialIdParam'
      responses:
        '200':
          description: Credential removed from locker successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Locker or credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lockers/{id}/consumers:
    get:
      operationId: listLockerConsumers
      summary: List locker consumers
      description: >-
        Returns all roles that have consumer access to the credentials
        in the specified Locker. Consumer roles are used by bots to
        retrieve credential values during automation execution.
      tags:
        - LockerConsumers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
      responses:
        '200':
          description: List of consumer roles for the locker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockerConsumerList'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Locker not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: addLockerConsumer
      summary: Add a locker consumer
      description: >-
        Grants a role consumer access to the credentials in the specified
        Locker. Bots assigned to this role can then retrieve credential
        values from this Locker during execution.
      tags:
        - LockerConsumers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockerConsumerPost'
      responses:
        '200':
          description: Consumer role added to locker successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockerConsumer'
        '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: Locker not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lockers/{id}/consumers/{roleId}:
    delete:
      operationId: removeLockerConsumer
      summary: Remove a locker consumer
      description: >-
        Revokes a role's consumer access to the credentials in the specified
        Locker. Bots assigned to this role will no longer be able to retrieve
        credential values through this Locker.
      tags:
        - LockerConsumers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
        - name: roleId
          in: path
          required: true
          description: Numeric ID of the consumer role to remove
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Consumer role removed from locker successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Locker or consumer role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lockers/{id}/members:
    get:
      operationId: listLockerMembers
      summary: Get locker members
      description: >-
        Returns all users who are members of the specified Locker. Members
        have management access to the Locker and can add or remove credentials
        and manage consumer role assignments.
      tags:
        - LockerMembers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
      responses:
        '200':
          description: List of locker members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockerMemberList'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Locker not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lockers/{id}/members/{userId}:
    put:
      operationId: updateLockerMember
      summary: Update locker member permissions
      description: >-
        Adds a user as a Locker member or updates their membership permissions.
        Locker members can manage the Locker's contents and access control
        configuration.
      tags:
        - LockerMembers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
        - $ref: '#/components/parameters/UserIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockerMemberUpdate'
      responses:
        '200':
          description: Locker member updated successfully
        '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: Locker or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: removeLockerMember
      summary: Remove a locker member
      description: >-
        Removes a user from Locker membership, revoking their ability to
        manage the Locker's credentials and access control settings.
      tags:
        - LockerMembers
      parameters:
        - $ref: '#/components/parameters/LockerIdParam'
        - $ref: '#/components/parameters/UserIdPathParam'
      responses:
        '200':
          description: Member removed from locker successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Locker or member not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  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
  parameters:
    CredentialIdParam:
      name: id
      in: path
      required: true
      description: Unique numeric identifier of the credential
      schema:
        type: integer
        format: int64
    AttributeValueIdParam:
      name: attributeValueId
      in: path
      required: true
      description: Unique numeric identifier of the credential attribute value
      schema:
        type: integer
        format: int64
    LockerIdParam:
      name: id
      in: path
      required: true
      description: Unique numeric identifier of the locker
      schema:
        type: integer
        format: int64
    UserIdPathParam:
      name: userId
      in: path
      required: true
      description: Unique numeric identifier of the user
      schema:
        type: integer
        format: int64
    ConsumedParam:
      name: consumed
      in: query
      required: false
      description: Whether to return attribute values in bot-consumption format
      schema:
        type: boolean
    CredentialAttributeIdParam:
      name: credentialAttributeId
      in: query
      required: false
      description: Filter attribute values by this credential attribute ID
      schema:
        type: integer
        format: int64
    UserIdQueryParam:
      name: userId
      in: query
      required: false
      description: Filter attribute values scoped to this user ID
      schema:
        type: integer
        format: int64
    EncryptionKeyParam:
      name: encryptionKey
      in: query
      required: false
      description: Encryption key identifier for decrypting attribute values
      schema:
        type: string
  schemas:
    Credential:
      type: object
      description: A credential stored in the Credential Vault with named attributes
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the credential
        name:
          type: string
          description: Human-readable name of the credential
        description:
          type: string
          description: Optional description of the credential's purpose
        ownerId:
          type: integer
          format: int64
          description: User ID of the credential owner
        attributes:
          type: array
          description: List of attribute definitions associated with this credential
          items:
            $ref: '#/components/schemas/CredentialAttribute'
        createdBy:
          type: integer
          format: int64
          description: ID of the user who created this credential
        createdOn

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/automation-anywhere/refs/heads/main/openapi/automation-anywhere-credential-vault-openapi.yml