openapi: 3.1.0
info:
  title: Tufin SecureChange REST API
  description: >-
    The Tufin SecureChange REST API automates security policy change workflows,
    enabling programmatic submission and management of access request tickets,
    approval workflows, and change implementation across network infrastructure.
    SecureChange integrates with ITSM platforms including ServiceNow, Jira, and
    Remedy for end-to-end change automation. Authentication uses HTTP Basic Auth.
  version: R25-2
  contact:
    name: Tufin Support
    url: https://www.tufin.com/support
  license:
    name: Tufin Terms of Use
    url: https://www.tufin.com/terms-of-use
externalDocs:
  description: Tufin SecureChange REST API Documentation
  url: https://forum.tufin.com/support/kc/latest/Content/Suite/RESTAPI/12309.htm
servers:
  - url: https://{tos_host}/securechangeworkflow/api/securechange
    description: Tufin SecureChange Server
    variables:
      tos_host:
        description: Hostname or IP address of the TOS server
        default: tufin.example.com
tags:
  - name: Tickets
    description: Create and manage security change tickets
  - name: Requests
    description: Access request workflows and approvals
  - name: Tasks
    description: Workflow tasks and approvals
  - name: Users
    description: User and group management
  - name: Workflow Definitions
    description: Workflow template definitions
paths:
  /tickets:
    get:
      operationId: getTickets
      summary: Get Tickets
      description: >-
        Retrieve a list of security change tickets, optionally filtered by status,
        requester, or time range.
      tags:
        - Tickets
      security:
        - basicAuth: []
      parameters:
        - name: status
          in: query
          description: Filter by ticket status (Open, Resolved, Rejected, Cancelled, In Progress)
          schema:
            type: string
            enum:
              - Open
              - Resolved
              - Rejected
              - Cancelled
              - In Progress
        - name: requester
          in: query
          description: Filter by requester username
          schema:
            type: string
        - name: start_date
          in: query
          description: Filter tickets created after this date (ISO 8601)
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          description: Filter tickets created before this date (ISO 8601)
          schema:
            type: string
            format: date-time
        - name: count
          in: query
          description: Number of tickets to return
          schema:
            type: integer
            default: 50
        - name: start
          in: query
          description: Offset for pagination
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of tickets
          content:
            application/json:
              schema:
                type: object
                properties:
                  tickets:
                    type: object
                    properties:
                      count:
                        type: integer
                      ticket:
                        type: array
                        items:
                          $ref: '#/components/schemas/Ticket'
        '401':
          description: Unauthorized
    post:
      operationId: createTicket
      summary: Create Ticket
      description: >-
        Submit a new security change ticket to the SecureChange workflow. The ticket
        type must match a configured workflow definition. Common types include
        access requests, firewall rule changes, and cleanup requests.
      tags:
        - Tickets
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketInput'
      responses:
        '200':
          description: Ticket created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
        '400':
          description: Invalid ticket data
        '401':
          description: Unauthorized
  /tickets/{ticketId}:
    get:
      operationId: getTicketById
      summary: Get Ticket By ID
      description: Retrieve a specific security change ticket by its identifier.
      tags:
        - Tickets
      security:
        - basicAuth: []
      parameters:
        - name: ticketId
          in: path
          required: true
          description: The unique identifier of the ticket
          schema:
            type: integer
      responses:
        '200':
          description: Ticket details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
        '404':
          description: Ticket not found
    put:
      operationId: updateTicket
      summary: Update Ticket
      description: Update the details of an existing change ticket.
      tags:
        - Tickets
      security:
        - basicAuth: []
      parameters:
        - name: ticketId
          in: path
          required: true
          description: The unique identifier of the ticket
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketInput'
      responses:
        '200':
          description: Ticket updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
        '404':
          description: Ticket not found
  /tickets/{ticketId}/tasks:
    get:
      operationId: getTicketTasks
      summary: Get Ticket Tasks
      description: Retrieve all workflow tasks associated with a ticket.
      tags:
        - Tickets
        - Tasks
      security:
        - basicAuth: []
      parameters:
        - name: ticketId
          in: path
          required: true
          description: The unique identifier of the ticket
          schema:
            type: integer
      responses:
        '200':
          description: List of tasks
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    type: object
                    properties:
                      task:
                        type: array
                        items:
                          $ref: '#/components/schemas/Task'
  /tickets/{ticketId}/tasks/{taskId}:
    get:
      operationId: getTaskById
      summary: Get Task By ID
      description: Retrieve a specific workflow task by ticket and task ID.
      tags:
        - Tasks
      security:
        - basicAuth: []
      parameters:
        - name: ticketId
          in: path
          required: true
          description: The unique identifier of the ticket
          schema:
            type: integer
        - name: taskId
          in: path
          required: true
          description: The unique identifier of the task
          schema:
            type: integer
      responses:
        '200':
          description: Task details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: Task not found
    put:
      operationId: updateTask
      summary: Update Task
      description: Update a workflow task (e.g., approve, reject, or provide implementation details).
      tags:
        - Tasks
      security:
        - basicAuth: []
      parameters:
        - name: ticketId
          in: path
          required: true
          description: The unique identifier of the ticket
          schema:
            type: integer
        - name: taskId
          in: path
          required: true
          description: The unique identifier of the task
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskUpdate'
      responses:
        '200':
          description: Task updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
  /workflow_definitions:
    get:
      operationId: getWorkflowDefinitions
      summary: Get Workflow Definitions
      description: Retrieve all workflow definitions (templates) configured in SecureChange.
      tags:
        - Workflow Definitions
      security:
        - basicAuth: []
      responses:
        '200':
          description: List of workflow definitions
          content:
            application/json:
              schema:
                type: object
                properties:
                  workflow_definitions:
                    type: object
                    properties:
                      workflow_definition:
                        type: array
                        items:
                          $ref: '#/components/schemas/WorkflowDefinition'
  /users:
    get:
      operationId: getUsers
      summary: Get Users
      description: Retrieve all users defined in SecureChange.
      tags:
        - Users
      security:
        - basicAuth: []
      parameters:
        - name: name
          in: query
          description: Filter by username
          schema:
            type: string
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: object
                    properties:
                      user:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using Tufin Orchestration Suite credentials.
        The authenticated user's TOS permissions apply to all API requests.
  schemas:
    Ticket:
      type: object
      description: A security change ticket in SecureChange
      properties:
        id:
          type: integer
          description: Unique identifier of the ticket
        subject:
          type: string
          description: Subject line of the ticket
        description:
          type: string
          description: Detailed description of the requested change
        status:
          type: string
          description: Current status of the ticket
          enum:
            - Open
            - Resolved
            - Rejected
            - Cancelled
            - In Progress
        priority:
          type: string
          description: Priority level
          enum:
            - Low
            - Normal
            - High
            - Critical
        requester:
          type: string
          description: Username of the ticket requester
        created:
          type: string
          format: date-time
          description: Ticket creation timestamp
        modified:
          type: string
          format: date-time
          description: Last modification timestamp
        workflow:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
          description: Workflow definition this ticket follows
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/Task'
          description: Workflow tasks for this ticket
    TicketInput:
      type: object
      description: Input for creating or updating a ticket
      required:
        - subject
        - workflow
      properties:
        subject:
          type: string
          description: Subject line of the ticket
        description:
          type: string
          description: Detailed description of the requested change
        priority:
          type: string
          description: Priority level
          enum:
            - Low
            - Normal
            - High
            - Critical
          default: Normal
        workflow:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Name of the workflow definition to use
        requester:
          type: string
          description: Username of the requester (defaults to authenticated user)
        steps:
          type: object
          description: Initial step data for the ticket
    Task:
      type: object
      description: A workflow task within a SecureChange ticket
      properties:
        id:
          type: integer
          description: Unique identifier of the task
        name:
          type: string
          description: Task name
        type:
          type: string
          description: Task type (e.g., approval, implementation, verification)
        status:
          type: string
          description: Current task status
          enum:
            - New
            - In Progress
            - Completed
            - Rejected
            - Not Started
        assignee:
          type: string
          description: Username assigned to this task
        due_date:
          type: string
          format: date-time
          description: Task due date
        fields:
          type: array
          items:
            type: object
          description: Dynamic task fields based on workflow configuration
    TaskUpdate:
      type: object
      description: Input for updating a task
      properties:
        status:
          type: string
          description: New task status
        comment:
          type: string
          description: Comment to add to the task
        fields:
          type: array
          items:
            type: object
          description: Updated field values
    WorkflowDefinition:
      type: object
      description: A workflow template definition in SecureChange
      properties:
        id:
          type: integer
          description: Workflow definition identifier
        name:
          type: string
          description: Workflow definition name
        description:
          type: string
          description: Description of when to use this workflow
        enabled:
          type: boolean
          description: Whether this workflow is available for new tickets
        steps:
          type: array
          items:
            type: object
          description: Workflow step definitions
    User:
      type: object
      description: A SecureChange user
      properties:
        id:
          type: integer
          description: User identifier
        username:
          type: string
          description: Login username
        email:
          type: string
          description: User email address
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
        groups:
          type: array
          items:
            type: string
          description: Groups the user belongs to