openapi: 3.0.3
info:
  title: BeyondTrust Password Safe API
  description: >-
    The BeyondTrust Password Safe API provides programmatic access to privileged
    credential management, secrets management, session management, and access
    request workflows. It enables developers to integrate privileged account
    security into CI/CD pipelines, automation frameworks, and enterprise
    applications.
  version: v3
  contact:
    name: BeyondTrust Support
    url: https://docs.beyondtrust.com/
  x-generated-from: documentation
servers:
  - url: https://{hostname}/BeyondTrust/api/public/v3
    description: BeyondTrust Password Safe API v3
    variables:
      hostname:
        default: beyondtrust.example.com
        description: Your BeyondTrust appliance hostname
security:
  - apiKeyAuth: []
tags:
  - name: Credentials
    description: Manage privileged account credentials and passwords
  - name: Requests
    description: Submit and manage access requests for privileged accounts
  - name: Sessions
    description: Manage privileged remote sessions
  - name: Managed Accounts
    description: Manage privileged accounts and their configurations
  - name: Managed Systems
    description: Manage systems registered in Password Safe
  - name: Secrets
    description: Manage secrets and secret store entries
  - name: Authentication
    description: API authentication and authorization
paths:
  /auth/signappin:
    post:
      operationId: signAppIn
      summary: BeyondTrust Sign App In
      description: Authenticates an application and creates a session. Returns a session token for subsequent API calls.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignAppInRequest'
            examples:
              SignAppInRequestExample:
                summary: Default signAppIn request
                x-microcks-default: true
                value:
                  ApplicationID: myapp-api
                  APIKey: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Authentication successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
              examples:
                SignAppIn200Example:
                  summary: Default signAppIn 200 response
                  x-microcks-default: true
                  value:
                    UserId: 42
                    EmailAddress: apiuser@example.com
                    UserName: api-service-account
                    Name: API Service Account
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /auth/signappout:
    post:
      operationId: signAppOut
      summary: BeyondTrust Sign App Out
      description: Terminates the current application session.
      tags:
        - Authentication
      responses:
        '200':
          description: Sign out successful.
        '401':
          description: Not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /requests:
    get:
      operationId: listRequests
      summary: BeyondTrust List Requests
      description: Returns all active access requests for the authenticated user.
      tags:
        - Requests
      responses:
        '200':
          description: List of active requests.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Request'
              examples:
                ListRequests200Example:
                  summary: Default listRequests 200 response
                  x-microcks-default: true
                  value:
                    - RequestID: 1001
                      Status: Approved
                      AccessType: View
                      AccountName: administrator
                      SystemName: prod-server-01
                      ExpiresDate: "2026-04-19T12:00:00Z"
                      RequestedDurationMinutes: 60
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createRequest
      summary: BeyondTrust Create Request
      description: Creates a new access request for a managed account.
      tags:
        - Requests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRequestBody'
            examples:
              CreateRequestRequestExample:
                summary: Default createRequest request
                x-microcks-default: true
                value:
                  SystemID: 10
                  AccountID: 20
                  DurationMinutes: 60
                  Reason: Maintenance window access
                  AccessType: View
      responses:
        '201':
          description: Request created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Request'
              examples:
                CreateRequest201Example:
                  summary: Default createRequest 201 response
                  x-microcks-default: true
                  value:
                    RequestID: 1002
                    Status: Pending
                    AccessType: View
                    AccountName: administrator
                    SystemName: prod-server-01
                    RequestedDurationMinutes: 60
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /requests/{requestId}:
    get:
      operationId: getRequest
      summary: BeyondTrust Get Request
      description: Returns a single access request by ID.
      tags:
        - Requests
      parameters:
        - name: requestId
          in: path
          required: true
          description: The unique identifier of the request.
          schema:
            type: integer
          example: 1001
      responses:
        '200':
          description: Request details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Request'
              examples:
                GetRequest200Example:
                  summary: Default getRequest 200 response
                  x-microcks-default: true
                  value:
                    RequestID: 1001
                    Status: Approved
                    AccessType: View
                    AccountName: administrator
                    SystemName: prod-server-01
                    ExpiresDate: "2026-04-19T12:00:00Z"
                    RequestedDurationMinutes: 60
        '404':
          description: Request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateRequest
      summary: BeyondTrust Update Request
      description: Approves, denies, or cancels an access request.
      tags:
        - Requests
      parameters:
        - name: requestId
          in: path
          required: true
          description: The unique identifier of the request.
          schema:
            type: integer
          example: 1001
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRequestBody'
            examples:
              UpdateRequestRequestExample:
                summary: Default updateRequest request
                x-microcks-default: true
                value:
                  Action: Approve
      responses:
        '200':
          description: Request updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Request'
              examples:
                UpdateRequest200Example:
                  summary: Default updateRequest 200 response
                  x-microcks-default: true
                  value:
                    RequestID: 1001
                    Status: Approved
                    AccessType: View
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteRequest
      summary: BeyondTrust Delete Request
      description: Cancels and deletes an access request.
      tags:
        - Requests
      parameters:
        - name: requestId
          in: path
          required: true
          description: The unique identifier of the request.
          schema:
            type: integer
          example: 1001
      responses:
        '200':
          description: Request cancelled.
        '404':
          description: Request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /requests/{requestId}/credentials:
    get:
      operationId: getRequestCredentials
      summary: BeyondTrust Get Request Credentials
      description: Retrieves the credentials for an approved access request.
      tags:
        - Credentials
      parameters:
        - name: requestId
          in: path
          required: true
          description: The unique identifier of the approved request.
          schema:
            type: integer
          example: 1001
      responses:
        '200':
          description: Credentials for the approved request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialResponse'
              examples:
                GetRequestCredentials200Example:
                  summary: Default getRequestCredentials 200 response
                  x-microcks-default: true
                  value:
                    Password: "Xk2!mP9@nQ7#rT5"
                    PrivateKey: null
        '403':
          description: Request not yet approved or already expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /managedaccounts:
    get:
      operationId: listManagedAccounts
      summary: BeyondTrust List Managed Accounts
      description: Returns a list of managed accounts available to the caller.
      tags:
        - Managed Accounts
      parameters:
        - name: systemName
          in: query
          description: Filter accounts by system name.
          required: false
          schema:
            type: string
          example: prod-server-01
        - name: accountName
          in: query
          description: Filter by account name.
          required: false
          schema:
            type: string
          example: administrator
      responses:
        '200':
          description: List of managed accounts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ManagedAccount'
              examples:
                ListManagedAccounts200Example:
                  summary: Default listManagedAccounts 200 response
                  x-microcks-default: true
                  value:
                    - AccountID: 20
                      AccountName: administrator
                      SystemID: 10
                      SystemName: prod-server-01
                      DomainName: example.com
                      AccountType: Local
                      LastChangeDate: "2026-04-01T00:00:00Z"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /managedsystems:
    get:
      operationId: listManagedSystems
      summary: BeyondTrust List Managed Systems
      description: Returns a list of managed systems registered in Password Safe.
      tags:
        - Managed Systems
      parameters:
        - name: name
          in: query
          description: Filter by system name.
          required: false
          schema:
            type: string
          example: prod-server-01
      responses:
        '200':
          description: List of managed systems.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ManagedSystem'
              examples:
                ListManagedSystems200Example:
                  summary: Default listManagedSystems 200 response
                  x-microcks-default: true
                  value:
                    - ManagedSystemID: 10
                      SystemName: prod-server-01
                      IPAddress: 10.1.1.10
                      Platform: Windows
                      NetworkAddress: prod-server-01.example.com
                      ContactEmail: admin@example.com
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /secrets-safe/secrets:
    get:
      operationId: listSecrets
      summary: BeyondTrust List Secrets
      description: Returns a list of secrets from the secrets safe store.
      tags:
        - Secrets
      parameters:
        - name: title
          in: query
          description: Filter secrets by title.
          required: false
          schema:
            type: string
          example: database-credentials
      responses:
        '200':
          description: List of secrets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Secret'
              examples:
                ListSecrets200Example:
                  summary: Default listSecrets 200 response
                  x-microcks-default: true
                  value:
                    - id: secret-a1b2c3
                      title: database-credentials
                      type: Password
                      folderName: Production
                      created: "2025-01-15T00:00:00Z"
                      lastModified: "2026-04-01T00:00:00Z"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createSecret
      summary: BeyondTrust Create Secret
      description: Creates a new secret in the secrets safe store.
      tags:
        - Secrets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
            examples:
              CreateSecretRequestExample:
                summary: Default createSecret request
                x-microcks-default: true
                value:
                  title: new-api-key
                  description: API key for production service
                  type: Password
                  password: "SecurePassword123!"
                  folderName: Production
      responses:
        '201':
          description: Secret created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
              examples:
                CreateSecret201Example:
                  summary: Default createSecret 201 response
                  x-microcks-default: true
                  value:
                    id: secret-d4e5f6
                    title: new-api-key
                    type: Password
                    folderName: Production
                    created: "2026-04-19T10:00:00Z"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /secrets-safe/secrets/{id}:
    get:
      operationId: getSecret
      summary: BeyondTrust Get Secret
      description: Returns a single secret by ID including its value.
      tags:
        - Secrets
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the secret.
          schema:
            type: string
          example: secret-a1b2c3
      responses:
        '200':
          description: Secret details including value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretWithValue'
              examples:
                GetSecret200Example:
                  summary: Default getSecret 200 response
                  x-microcks-default: true
                  value:
                    id: secret-a1b2c3
                    title: database-credentials
                    type: Password
                    password: "Xk2!mP9@nQ7#rT5"
                    folderName: Production
                    created: "2025-01-15T00:00:00Z"
        '404':
          description: Secret not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteSecret
      summary: BeyondTrust Delete Secret
      description: Deletes a secret from the secrets safe store.
      tags:
        - Secrets
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the secret.
          schema:
            type: string
          example: secret-a1b2c3
      responses:
        '200':
          description: Secret deleted.
        '404':
          description: Secret not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        PS-Auth key={APIKey}; runas={AppID}. Authenticate by first calling
        /auth/signappin to get a session cookie, then use PS-Auth header
        for subsequent requests.
  schemas:
    ErrorResponse:
      title: Error Response
      description: Standard BeyondTrust API error response.
      type: object
      properties:
        Message:
          type: string
          description: Human-readable error message.
          example: Access denied
        ErrorCode:
          type: integer
          description: Numeric error code.
          example: 4003
    SignAppInRequest:
      title: Sign App In Request
      description: Authentication credentials for API sign-in.
      type: object
      required:
        - ApplicationID
        - APIKey
      properties:
        ApplicationID:
          type: string
          description: The Application ID registered in BeyondTrust.
          example: myapp-api
        APIKey:
          type: string
          description: The API key for the application.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    SessionResponse:
      title: Session Response
      description: Authenticated user session details.
      type: object
      properties:
        UserId:
          type: integer
          description: Internal user ID.
          example: 42
        EmailAddress:
          type: string
          format: email
          description: Email address of the authenticated user.
          example: apiuser@example.com
        UserName:
          type: string
          description: Username of the authenticated user.
          example: api-service-account
        Name:
          type: string
          description: Display name of the authenticated user.
          example: API Service Account
    Request:
      title: Request
      description: An access request for a privileged account.
      type: object
      properties:
        RequestID:
          type: integer
          description: Unique identifier of the request.
          example: 1001
        Status:
          type: string
          description: Current status of the request.
          enum:
            - Pending
            - Approved
            - Denied
            - Expired
            - Cancelled
          example: Approved
        AccessType:
          type: string
          description: Type of access requested.
          enum:
            - View
            - RDP
            - SSH
            - App
          example: View
        AccountName:
          type: string
          description: Name of the privileged account.
          example: administrator
        AccountID:
          type: integer
          description: ID of the managed account.
          example: 20
        SystemName:
          type: string
          description: Name of the target system.
          example: prod-server-01
        SystemID:
          type: integer
          description: ID of the managed system.
          example: 10
        ExpiresDate:
          type: string
          format: date-time
          nullable: true
          description: When the approved request expires.
          example: "2026-04-19T12:00:00Z"
        RequestedDurationMinutes:
          type: integer
          description: Requested duration in minutes.
          example: 60
        Reason:
          type: string
          nullable: true
          description: Reason provided for the access request.
          example: Maintenance window access
        RequestDate:
          type: string
          format: date-time
          description: When the request was created.
          example: "2026-04-19T10:00:00Z"
    CreateRequestBody:
      title: Create Request Body
      description: Request body for creating an access request.
      type: object
      required:
        - SystemID
        - AccountID
        - DurationMinutes
        - Reason
        - AccessType
      properties:
        SystemID:
          type: integer
          description: ID of the managed system.
          example: 10
        AccountID:
          type: integer
          description: ID of the managed account.
          example: 20
        DurationMinutes:
          type: integer
          description: Requested access duration in minutes.
          example: 60
        Reason:
          type: string
          description: Business justification for the access request.
          example: Maintenance window access
        AccessType:
          type: string
          description: Type of access requested.
          enum:
            - View
            - RDP
            - SSH
            - App
          example: View
    UpdateRequestBody:
      title: Update Request Body
      description: Request body for approving, denying, or cancelling a request.
      type: object
      required:
        - Action
      properties:
        Action:
          type: string
          description: The action to perform on the request.
          enum:
            - Approve
            - Deny
            - Cancel
          example: Approve
        Reason:
          type: string
          description: Reason for the action.
          example: Approved for maintenance window
    CredentialResponse:
      title: Credential Response
      description: Credentials retrieved for an approved access request.
      type: object
      properties:
        Password:
          type: string
          nullable: true
          description: The retrieved password. Only present for password-based accounts.
          example: "Xk2!mP9@nQ7#rT5"
        PrivateKey:
          type: string
          nullable: true
          description: SSH private key. Only present for SSH key-based accounts.
          example: null
    ManagedAccount:
      title: Managed Account
      description: A privileged account managed by BeyondTrust Password Safe.
      type: object
      properties:
        AccountID:
          type: integer
          description: Unique identifier of the managed account.
          example: 20
        AccountName:
          type: string
          description: Name of the privileged account.
          example: administrator
        SystemID:
          type: integer
          description: ID of the managed system.
          example: 10
        SystemName:
          type: string
          description: Name of the system containing this account.
          example: prod-server-01
        DomainName:
          type: string
          nullable: true
          description: Domain name for domain accounts.
          example: example.com
        AccountType:
          type: string
          description: Type of account.
          enum:
            - Local
            - Domain
            - ServiceAccount
          example: Local
        LastChangeDate:
          type: string
          format: date-time
          nullable: true
          description: When the password was last changed.
          example: "2026-04-01T00:00:00Z"
        PasswordFallbackFlag:
          type: boolean
          description: Whether password fallback is enabled.
          example: false
    ManagedSystem:
      title: Managed System
      description: A system registered in BeyondTrust Password Safe.
      type: object
      properties:
        ManagedSystemID:
          type: integer
          description: Unique identifier of the managed system.
          example: 10
        SystemName:
          type: string
          description: Name of the system.
          example: prod-server-01
        IPAddress:
          type: string
          description: IP address of the system.
          example: 10.1.1.10
        Platform:
          type: string
          description: Operating system platform.
          enum:
            - Windows
            - Linux
            - Unix
            - macOS
          example: Windows
        NetworkAddress:
          type: string
          description: Network hostname or FQDN.
          example: prod-server-01.example.com
        ContactEmail:
          type: string
          format: email
          nullable: true
          description: Contact email for this system.
          example: admin@example.com
    Secret:
      title: Secret
      description: A secret stored in BeyondTrust Secrets Safe.
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the secret.
          example: secret-a1b2c3
        title:
          type: string
          description: Title or name of the secret.
          example: database-credentials
        description:
          type: string
          nullable: true
          description: Description of the secret.
          example: Production database credentials
        type:
          type: string
          description: Type of secret.
          enum:
            - Password
            - Text
            - File
          example: Password
        folderName:
          type: string
          nullable: true
          description: Folder organizing this secret.
          example: Production
        created:
          type: string
          format: date-time
          description: When the secret was created.
          example: "2025-01-15T00:00:00Z"
        lastModified:
          type: string
          format: date-time
          description: When the secret was last modified.
          example: "2026-04-01T00:00:00Z"
    SecretWithValue:
      title: Secret With Value
      description: A secret including its sensitive value.
      type: object
      properties:
        id:
          type: string
          description: Unique identifier.
          example: secret-a1b2c3
        title:
          type: string
          description: Secret title.
          example: database-credentials
        type:
          type: string
          description: Secret type.
          example: Password
        password:
          type: string
          nullable: true
          description: Password value (for Password type secrets).
          example: "Xk2!mP9@nQ7#rT5"
        text:
          type: string
          nullable: true
          description: Text value (for Text type secrets).
          example: null
        folderName:
          type: string
          nullable: true
          description: Folder name.
          example: Production
        created:
          type: string
          format: date-time
          description: Creation timestamp.
          example: "2025-01-15T00:00:00Z"
    CreateSecretRequest:
      title: Create Secret Request
      description: Request body for creating a new secret.
      type: object
      required:
        - title
        - type
      properties:
        title:
          type: string
          description: Title of the secret.
          example: new-api-key
        description:
          type: string
          description: Description of the secret.
          example: API key for production service
        type:
          type: string
          description: Type of secret.
          enum:
            - Password
            - Text
            - File
          example: Password
        password:
          type: string
          description: Password value (for Password type).
          example: "SecurePassword123!"
        text:
          type: string
          description: Text value (for Text type).
          example: my-secret-text
        folderName:
          type: string
          description: Folder to store the secret in.
          example: Production