openapi: 3.0.3
info:
  title: BeyondTrust Password Safe Authentication Secrets 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: Secrets
  description: Manage secrets and secret store entries
paths:
  /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:
  schemas:
    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
    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'
    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
    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'
  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.