openapi: 3.1.0
info:
  title: Tufin SecureChange REST Compliance Tickets 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
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
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
      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'
components:
  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
  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.
externalDocs:
  description: Tufin SecureChange REST API Documentation
  url: https://forum.tufin.com/support/kc/latest/Content/Suite/RESTAPI/12309.htm