openapi: 3.0.3
info:
  title: BetterCloud Platform API
  description: >-
    The BetterCloud Platform API provides REST API access for managing SaaS
    application operations, automated workflows, user lifecycle management,
    and security policies across enterprise SaaS environments. It enables IT
    and security teams to programmatically manage users, groups, directories,
    and automation workflows across 100+ integrated SaaS applications.
  version: v1
  contact:
    name: BetterCloud Developer Support
    url: https://developer.bettercloud.com/
  x-generated-from: documentation
servers:
  - url: https://api.bettercloud.com/v1
    description: BetterCloud Platform API v1
security:
  - apiKeyAuth: []
tags:
  - name: Users
    description: Manage users across integrated SaaS applications
  - name: Groups
    description: Manage groups and group memberships
  - name: Workflows
    description: Manage automation workflows and triggers
  - name: Policies
    description: Manage security and compliance policies
  - name: Actions
    description: Execute actions against SaaS applications
  - name: Integrations
    description: Manage SaaS application integrations and connections
  - name: Events
    description: Query audit events and activity logs
paths:
  /users:
    get:
      operationId: listUsers
      summary: BetterCloud List Users
      description: Returns a paginated list of users discovered across all integrated SaaS applications.
      tags:
        - Users
      parameters:
        - name: page
          in: query
          description: Page number for pagination.
          required: false
          schema:
            type: integer
            default: 1
          example: 1
        - name: per_page
          in: query
          description: Number of results per page (max 100).
          required: false
          schema:
            type: integer
            default: 25
            maximum: 100
          example: 25
        - name: email
          in: query
          description: Filter users by email address.
          required: false
          schema:
            type: string
            format: email
          example: jsmith@example.com
        - name: status
          in: query
          description: Filter users by status.
          required: false
          schema:
            type: string
            enum:
              - active
              - suspended
              - deprovisioned
          example: active
      responses:
        '200':
          description: Paginated list of users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
              examples:
                ListUsers200Example:
                  summary: Default listUsers 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - id: user-a1b2c3d4
                        email: jsmith@example.com
                        first_name: Jane
                        last_name: Smith
                        status: active
                        department: Engineering
                        title: Senior Engineer
                        created_at: "2025-01-15T10:00:00Z"
                        updated_at: "2026-04-01T08:30:00Z"
                    meta:
                      page: 1
                      per_page: 25
                      total: 150
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{id}:
    get:
      operationId: getUser
      summary: BetterCloud Get User
      description: Returns a single user by ID with their SaaS application details.
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the user.
          schema:
            type: string
          example: user-a1b2c3d4
      responses:
        '200':
          description: User details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
              examples:
                GetUser200Example:
                  summary: Default getUser 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: user-a1b2c3d4
                      email: jsmith@example.com
                      first_name: Jane
                      last_name: Smith
                      status: active
                      department: Engineering
                      title: Senior Engineer
                      manager_email: manager@example.com
                      location: San Francisco
                      created_at: "2025-01-15T10:00:00Z"
                      updated_at: "2026-04-01T08:30:00Z"
        '404':
          description: User not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateUser
      summary: BetterCloud Update User
      description: Updates user attributes across integrated SaaS applications.
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the user.
          schema:
            type: string
          example: user-a1b2c3d4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
            examples:
              UpdateUserRequestExample:
                summary: Default updateUser request
                x-microcks-default: true
                value:
                  department: Product
                  title: Product Manager
      responses:
        '200':
          description: User updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
              examples:
                UpdateUser200Example:
                  summary: Default updateUser 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: user-a1b2c3d4
                      email: jsmith@example.com
                      first_name: Jane
                      last_name: Smith
                      status: active
                      department: Product
                      title: Product Manager
                      updated_at: "2026-04-19T10:00:00Z"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{id}/suspend:
    post:
      operationId: suspendUser
      summary: BetterCloud Suspend User
      description: Suspends a user across all integrated SaaS applications.
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the user.
          schema:
            type: string
          example: user-a1b2c3d4
      responses:
        '200':
          description: User suspended successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
              examples:
                SuspendUser200Example:
                  summary: Default suspendUser 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: user-a1b2c3d4
                      email: jsmith@example.com
                      status: suspended
                      updated_at: "2026-04-19T10:00:00Z"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{id}/deprovision:
    post:
      operationId: deprovisionUser
      summary: BetterCloud Deprovision User
      description: Deprovisions a user and removes access across all integrated SaaS applications.
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the user.
          schema:
            type: string
          example: user-a1b2c3d4
      responses:
        '200':
          description: User deprovisioned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
              examples:
                DeprovisionUser200Example:
                  summary: Default deprovisionUser 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: user-a1b2c3d4
                      email: jsmith@example.com
                      status: deprovisioned
                      updated_at: "2026-04-19T10:00:00Z"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /groups:
    get:
      operationId: listGroups
      summary: BetterCloud List Groups
      description: Returns a paginated list of groups from integrated directory services.
      tags:
        - Groups
      parameters:
        - name: page
          in: query
          description: Page number.
          required: false
          schema:
            type: integer
            default: 1
          example: 1
        - name: per_page
          in: query
          description: Results per page.
          required: false
          schema:
            type: integer
            default: 25
          example: 25
      responses:
        '200':
          description: Paginated list of groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupListResponse'
              examples:
                ListGroups200Example:
                  summary: Default listGroups 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - id: group-x1y2z3
                        name: Engineering Team
                        email: engineering@example.com
                        member_count: 45
                        created_at: "2024-06-01T00:00:00Z"
                    meta:
                      page: 1
                      per_page: 25
                      total: 20
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createGroup
      summary: BetterCloud Create Group
      description: Creates a new group in the connected directory service.
      tags:
        - Groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreateRequest'
            examples:
              CreateGroupRequestExample:
                summary: Default createGroup request
                x-microcks-default: true
                value:
                  name: New Team
                  email: newteam@example.com
                  description: New team group
      responses:
        '201':
          description: Group created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
              examples:
                CreateGroup201Example:
                  summary: Default createGroup 201 response
                  x-microcks-default: true
                  value:
                    data:
                      id: group-a9b8c7
                      name: New Team
                      email: newteam@example.com
                      member_count: 0
                      created_at: "2026-04-19T10:00:00Z"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /groups/{id}:
    get:
      operationId: getGroup
      summary: BetterCloud Get Group
      description: Returns a single group with its members.
      tags:
        - Groups
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the group.
          schema:
            type: string
          example: group-x1y2z3
      responses:
        '200':
          description: Group details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
              examples:
                GetGroup200Example:
                  summary: Default getGroup 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: group-x1y2z3
                      name: Engineering Team
                      email: engineering@example.com
                      member_count: 45
                      created_at: "2024-06-01T00:00:00Z"
        '404':
          description: Group not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteGroup
      summary: BetterCloud Delete Group
      description: Deletes a group from the connected directory service.
      tags:
        - Groups
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the group.
          schema:
            type: string
          example: group-x1y2z3
      responses:
        '204':
          description: Group deleted successfully.
        '404':
          description: Group not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /groups/{id}/members:
    get:
      operationId: listGroupMembers
      summary: BetterCloud List Group Members
      description: Returns the members of a specific group.
      tags:
        - Groups
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the group.
          schema:
            type: string
          example: group-x1y2z3
      responses:
        '200':
          description: List of group members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMemberListResponse'
              examples:
                ListGroupMembers200Example:
                  summary: Default listGroupMembers 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - user_id: user-a1b2c3d4
                        email: jsmith@example.com
                        name: Jane Smith
                        role: member
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addGroupMember
      summary: BetterCloud Add Group Member
      description: Adds a user to a group.
      tags:
        - Groups
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the group.
          schema:
            type: string
          example: group-x1y2z3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupMemberAddRequest'
            examples:
              AddGroupMemberRequestExample:
                summary: Default addGroupMember request
                x-microcks-default: true
                value:
                  user_id: user-a1b2c3d4
      responses:
        '201':
          description: Member added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMemberResponse'
              examples:
                AddGroupMember201Example:
                  summary: Default addGroupMember 201 response
                  x-microcks-default: true
                  value:
                    data:
                      user_id: user-a1b2c3d4
                      email: jsmith@example.com
                      role: member
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /workflows:
    get:
      operationId: listWorkflows
      summary: BetterCloud List Workflows
      description: Returns a paginated list of all automation workflows.
      tags:
        - Workflows
      parameters:
        - name: page
          in: query
          description: Page number.
          required: false
          schema:
            type: integer
          example: 1
        - name: status
          in: query
          description: Filter by workflow status.
          required: false
          schema:
            type: string
            enum:
              - active
              - inactive
              - draft
          example: active
      responses:
        '200':
          description: Paginated list of workflows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowListResponse'
              examples:
                ListWorkflows200Example:
                  summary: Default listWorkflows 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - id: wf-100200
                        name: Employee Offboarding
                        description: Automated offboarding workflow for departing employees
                        status: active
                        trigger_type: manual
                        action_count: 12
                        created_at: "2025-03-01T00:00:00Z"
                        updated_at: "2026-04-01T00:00:00Z"
                    meta:
                      page: 1
                      per_page: 25
                      total: 8
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createWorkflow
      summary: BetterCloud Create Workflow
      description: Creates a new automation workflow.
      tags:
        - Workflows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowCreateRequest'
            examples:
              CreateWorkflowRequestExample:
                summary: Default createWorkflow request
                x-microcks-default: true
                value:
                  name: New Employee Onboarding
                  description: Automated onboarding workflow for new hires
                  trigger_type: event
                  status: draft
      responses:
        '201':
          description: Workflow created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
              examples:
                CreateWorkflow201Example:
                  summary: Default createWorkflow 201 response
                  x-microcks-default: true
                  value:
                    data:
                      id: wf-100300
                      name: New Employee Onboarding
                      description: Automated onboarding workflow for new hires
                      status: draft
                      trigger_type: event
                      action_count: 0
                      created_at: "2026-04-19T10:00:00Z"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /workflows/{id}:
    get:
      operationId: getWorkflow
      summary: BetterCloud Get Workflow
      description: Returns a single workflow by ID.
      tags:
        - Workflows
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the workflow.
          schema:
            type: string
          example: wf-100200
      responses:
        '200':
          description: Workflow details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
              examples:
                GetWorkflow200Example:
                  summary: Default getWorkflow 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: wf-100200
                      name: Employee Offboarding
                      description: Automated offboarding workflow for departing employees
                      status: active
                      trigger_type: manual
                      action_count: 12
                      created_at: "2025-03-01T00:00:00Z"
                      updated_at: "2026-04-01T00:00:00Z"
        '404':
          description: Workflow not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteWorkflow
      summary: BetterCloud Delete Workflow
      description: Deletes an automation workflow.
      tags:
        - Workflows
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the workflow.
          schema:
            type: string
          example: wf-100200
      responses:
        '204':
          description: Workflow deleted successfully.
        '404':
          description: Workflow not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /workflows/{id}/run:
    post:
      operationId: runWorkflow
      summary: BetterCloud Run Workflow
      description: Manually triggers a workflow execution for specified users.
      tags:
        - Workflows
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the workflow.
          schema:
            type: string
          example: wf-100200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowRunRequest'
            examples:
              RunWorkflowRequestExample:
                summary: Default runWorkflow request
                x-microcks-default: true
                value:
                  user_ids:
                    - user-a1b2c3d4
      responses:
        '202':
          description: Workflow execution initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunResponse'
              examples:
                RunWorkflow202Example:
                  summary: Default runWorkflow 202 response
                  x-microcks-default: true
                  value:
                    data:
                      execution_id: exec-900100
                      workflow_id: wf-100200
                      status: running
                      started_at: "2026-04-19T10:00:00Z"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /events:
    get:
      operationId: listEvents
      summary: BetterCloud List Events
      description: Returns a paginated list of audit events and activity logs.
      tags:
        - Events
      parameters:
        - name: page
          in: query
          description: Page number.
          required: false
          schema:
            type: integer
          example: 1
        - name: from
          in: query
          description: Start date for event filter (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
          example: "2026-04-01T00:00:00Z"
        - name: to
          in: query
          description: End date for event filter (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
          example: "2026-04-19T23:59:59Z"
        - name: type
          in: query
          description: Filter by event type.
          required: false
          schema:
            type: string
          example: user.suspended
        - name: user_id
          in: query
          description: Filter events for a specific user.
          required: false
          schema:
            type: string
          example: user-a1b2c3d4
      responses:
        '200':
          description: Paginated list of events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventListResponse'
              examples:
                ListEvents200Example:
                  summary: Default listEvents 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - id: evt-500100
                        type: user.suspended
                        actor_email: admin@example.com
                        target_email: jsmith@example.com
                        description: User suspended via BetterCloud workflow
                        occurred_at: "2026-04-18T14:00:00Z"
                    meta:
                      page: 1
                      per_page: 25
                      total: 500
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /integrations:
    get:
      operationId: listIntegrations
      summary: BetterCloud List Integrations
      description: Returns a list of all configured SaaS application integrations.
      tags:
        - Integrations
      responses:
        '200':
          description: List of integrations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationListResponse'
              examples:
                ListIntegrations200Example:
                  summary: Default listIntegrations 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - id: int-g001
                        name: Google Workspace
                        type: google_workspace
                        status: connected
                        connected_at: "2025-01-10T00:00:00Z"
                      - id: int-s001
                        name: Slack
                        type: slack
                        status: connected
                        connected_at: "2025-01-10T00:00:00Z"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key authentication. Provide your BetterCloud API key in the
        X-API-Key header. Keys can be generated from the BetterCloud
        developer portal.
  schemas:
    ErrorResponse:
      title: Error Response
      description: Standard error response from BetterCloud API.
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: RESOURCE_NOT_FOUND
        id:
          type: string
          description: Unique identifier for this error occurrence.
          example: err-500123
        href:
          type: string
          description: Link to documentation for this error code.
          example: https://developer.bettercloud.com/errors/RESOURCE_NOT_FOUND
        reason:
          type: string
          description: Human-readable explanation of the error.
          example: The requested resource was not found
      required:
        - code
        - id
        - href
        - reason
    MetaResponse:
      title: Meta Response
      description: Pagination metadata for list responses.
      type: object
      properties:
        page:
          type: integer
          description: Current page number.
          example: 1
        per_page:
          type: integer
          description: Number of items per page.
          example: 25
        total:
          type: integer
          description: Total number of items.
          example: 150
    User:
      title: User
      description: A user discovered and managed across BetterCloud integrations.
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the user in BetterCloud.
          example: user-a1b2c3d4
        email:
          type: string
          format: email
          description: Primary email address of the user.
          example: jsmith@example.com
        first_name:
          type: string
          description: User's first name.
          example: Jane
        last_name:
          type: string
          description: User's last name.
          example: Smith
        status:
          type: string
          description: Current status of the user.
          enum:
            - active
            - suspended
            - deprovisioned
          example: active
        department:
          type: string
          nullable: true
          description: Department or organizational unit.
          example: Engineering
        title:
          type: string
          nullable: true
          description: Job title.
          example: Senior Engineer
        manager_email:
          type: string
          format: email
          nullable: true
          description: Email of the user's manager.
          example: manager@example.com
        location:
          type: string
          nullable: true
          description: Office location.
          example: San Francisco
        created_at:
          type: string
          format: date-time
          description: When the user was first discovered.
          example: "2025-01-15T10:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: When the user record was last updated.
          example: "2026-04-01T08:30:00Z"
    UserListResponse:
      title: User List Response
      description: Paginated list of users.
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        meta:
          $ref: '#/components/schemas/MetaResponse'
    UserResponse:
      title: User Response
      description: Single user response.
      type: object
      properties:
        data:
          $ref: '#/components/schemas/User'
    UserUpdateRequest:
      title: User Update Request
      description: Fields to update on a user (all optional).
      type: object
      properties:
        first_name:
          type: string
          description: New first name.
          example: Jane
        last_name:
          type: string
          description: New last name.
          example: Smith
        department:
          type: string
          description: New department.
          example: Product
        title:
          type: string
          description: New job title.
          example: Product Manager
        location:
          type: string
          description: New office location.
          example: New York
    Group:
      title: Group
      description: A group from an integrated directory service.
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the group.
          example: group-x1y2z3
        name:
          type: string
          description: Display name of the group.
          example: Engineering Team
        email:
          type: string
          format: email
          nullable: true
          description: Email address of the group.
          example: engineering@example.com
        description:
          type: string
          nullable: true
          description: Description of the group.
          example: Engineering department group
        member_count:
          type: integer
          description: Number of members in the group.
          example: 45
        created_at:
          type: string
          format: date-time
          description: When the group was created.
          example: "2024-06-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: When the group was last updated.
          example: "2026-03-01T00:00:00Z"
    GroupListResponse:
      title: Group List Response
      description: Paginated list of groups.
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Group'
        meta:
          $ref: '#/components/schemas/MetaResponse'
    GroupResponse:
      title: Group Response
      description: Single group response.
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Group'
    GroupCreateRequest:
      title: Group Create Request
      description: Request body for creating a group.
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Display name of the group.
          example: New Team
        email:
          type: string
          format: email
          description: Email address of the group.
          example: newteam@example.com
        description:
          type: string
          description: Group description.
          example: New team group
    GroupMember:
      title: Group Member
      description: A member of a group.
      type: object
      properties:
        user_id:
          type: string
          description: Unique identifier of the user.
          example: user-a1b2c3d4
        email:
          type: string
          format: email
          description: Email of the group member.
          example: jsmith@example.com
        name:
          type: string
          description: Display name of the member.
          example: Jane Smith
        role:
          type: string
          description: Role in the group.
          enum:
            - owner
            - manager
            - member
          example: member
    GroupMemberListResponse:
      title: Group Member List Response
      description: List of group members.
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GroupMember'
    GroupMemberResponse:
      title: Group Member Response
      description: Single group member response.
      type: object
      properties:
        data:
          $ref: '#/components/schemas/GroupMember'
    GroupMemberAddRequest:
      title: Group Member Add Request
      description: Request body for adding a member to a group.
      type: object
      required:
        - user_id
      properties:
        user_id:
          type: string
          description: ID of the user to add to the group.
          example: user-a1b2c3d4
        role:
          type: string
          description: Role to assign in the group.
          enum:
            - owner
            - manager
            - member
          example: member
    Workflow:
      title: Workflow
      description: An automation workflow that can be triggered to execute actions across SaaS applications.
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the workflow.
          example: wf-100200
        name:
          type: string
          description: Display name of the workflow.
          example: Employee Offboarding
        description:
          type: string
          nullable: true
          description: Description of what the workflow does.
          example: Automated offboarding workflow for departing employees
        status:
          type: string
          description: Current status of the workflow.
          enum:
            - active
            - inactive
            - draft
          example: active
        trigger_type:
          type: string
          description: How the workflow is triggered.
          enum:
            - manual
            - event
            - scheduled
          example: manual
        action_count:
          type: integer
          description: Number of actions in the workflow.
          example: 12
        created_at:
          type: string
          format: date-time
          description: When the workflow was created.
          example: "2025-03-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: When the workflow was last updated.
          example: "2026-04-01T00:00:00Z"
    WorkflowListResponse:
      title: Workflow List Response
      description: Paginated list of workflows.
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Workflow'
        meta:
          $ref: '#/components/schemas/MetaResponse'
    WorkflowResponse:
      title: Workflow Response
      description: Single workflow response.
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Workflow'
    WorkflowCreateRequest:
      title: Workflow Create Request
      description: Request body for creating a workflow.
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the workflow.
          example: New Employee Onboarding
        description:
          type: string
          description: Description of the workflow.
          example: Automated onboarding workflow for new hires
        trigger_type:
          type: string
          description: Trigger type for the workflow.
          enum:
            - manual
            - event
            - scheduled
          example: event
        status:
          type: string
          description: Initial status.
          enum:
            - active
            - draft
          example: draft
    WorkflowRunRequest:
      title: Workflow Run Request
      description: Request body for triggering a workflow execution.
      type: object
      required:
        - user_ids
      properties:
        user_ids:
          type: array
          items:
            type: string
          description: List of user IDs to run the workflow for.
          example:
            - user-a1b2c3d4
    WorkflowRunResponse:
      title: Workflow Run Response
      description: Response from triggering a workflow execution.
      type: object
      properties:
        data:
          type: object
          properties:
            execution_id:
              type: string
              description: Unique ID of this workflow execution.
              example: exec-900100
            workflow_id:
              type: string
              description: ID of the workflow being executed.
              example: wf-100200
            status:
              type: string
              description: Current execution status.
              enum:
                - pending
                - running
                - completed
                - failed
              example: running
            started_at:
              type: string
              format: date-time
              description: When the execution started.
              example: "2026-04-19T10:00:00Z"
    Event:
      title: Event
      description: An audit event recording activity in BetterCloud or connected SaaS applications.
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the event.
          example: evt-500100
        type:
          type: string
          description: Event type in dot-notation (e.g., user.suspended, group.created).
          example: user.suspended
        actor_email:
          type: string
          format: email
          nullable: true
          description: Email of the user or system that triggered the event.
          example: admin@example.com
        target_email:
          type: string
          format: email
          nullable: true
          description: Email of the user or resource affected by the event.
          example: jsmith@example.com
        description:
          type: string
          description: Human-readable description of what happened.
          example: User suspended via BetterCloud workflow
        occurred_at:
          type: string
          format: date-time
          description: When the event occurred.
          example: "2026-04-18T14:00:00Z"
    EventListResponse:
      title: Event List Response
      description: Paginated list of audit events.
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        meta:
          $ref: '#/components/schemas/MetaResponse'
    Integration:
      title: Integration
      description: A connected SaaS application integration in BetterCloud.
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the integration.
          example: int-g001
        name:
          type: string
          description: Display name of the integration.
          example: Google Workspace
        type:
          type: string
          description: Integration type identifier.
          example: google_workspace
        status:
          type: string
          description: Connection status.
          enum:
            - connected
            - disconnected
            - error
          example: connected
        connected_at:
          type: string
          format: date-time
          nullable: true
          description: When the integration was connected.
          example: "2025-01-10T00:00:00Z"
    IntegrationListResponse:
      title: Integration List Response
      description: List of configured SaaS integrations.
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Integration'