openapi: 3.0.0
info:
  description: >
    This document specifies a **Flow Composer RESTful API** for **WSO2
    Identity Server**.
  version: '1.0'
  title: WSO2 Identity Server - Flow Management Rest API
  termsOfService: http://swagger.io/terms/
  contact:
    name: WSO2
    url: http://wso2.com/identity-server/
    email: architecture@wso2.org
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

security:
  - OAuth2: []
  - BasicAuth: []

servers:
  - url: https://{server-url}/t/{tenant-domain}/api/server/v1
    variables:
      tenant-domain:
        default: carbon.super
      server-url:
        default: localhost:9443

paths:
  /flow:
    put:
      summary: Create or update the complete flow
      operationId: updateFlow
      tags:
        - Flow Composer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowRequest'
      responses:
        '200':
          description: Flow successfully updated
        '201':
          description: Flow successfully created
        '400':
          description: Invalid request body or unsupported flow type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Flow type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Encountered a server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    get:
      summary: Retrieve the complete flow
      operationId: getFlow
      tags:
        - Flow Composer
      parameters:
        - in: query
          name: flowType
          required: true
          schema:
            type: string
            enum: [REGISTRATION, PASSWORD_RECOVERY, ASK_PASSWORD]
          description: Type of the flow to retrieve
      responses:
        '200':
          description: Successfully retrieved the flow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowResponse'
        '400':
          description: Invalid flow type specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Flow of specified type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete the flow
      operationId: deleteFlow
      tags:
        - Flow Composer
      parameters:
        - in: query
          name: flowType
          required: true
          schema:
            type: string
            enum: [REGISTRATION, PASSWORD_RECOVERY, ASK_PASSWORD]
          description: Type of the flow to delete
      responses:
        '204':
          description: Flow successfully deleted
        '400':
          description: Invalid request body or unsupported flow type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Encountered a server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /flow/meta:
    get:
      summary: Retrieve metadata related to a flow type
      operationId: getFlowMeta
      tags:
        - Flow Composer
      parameters:
        - in: query
          name: flowType
          required: true
          schema:
            type: string
            enum: [REGISTRATION, PASSWORD_RECOVERY, ASK_PASSWORD]
          description: Type of the flow to get metadata for
      responses:
        '200':
          description: Successfully retrieved flow metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowMetaResponse'
        '400':
          description: Invalid flow type specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Metadata for specified flow type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /flow/configs:
    get:
      summary: Retrieve flow management configuration
      operationId: getFlowConfigs
      tags:
        - Flow Configuration
      responses:
        '200':
          description: Successfully retrieved flow configurations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FlowConfig'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /flow/config:
    get:
      summary: Retrieve metadata related to a flow type
      operationId: getFlowConfigForFlow
      tags:
        - Flow Configuration
      parameters:
        - in: query
          name: flowType
          required: true
          schema:
            type: string
            enum: [REGISTRATION, PASSWORD_RECOVERY, ASK_PASSWORD]
          description: Type of the flow to get configurations for
      responses:
        '200':
          description: Successfully retrieved flow configurations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowConfig'
        '400':
          description: Invalid flow type specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      summary: Update the flow configuration
      operationId: updateFlowConfig
      tags:
        - Flow Configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowConfigPatchModel'
      responses:
        '200':
          description: Flow successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowConfig'
        '400':
          description: Invalid request body or unsupported flow type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Flow type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Encountered a server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /flow/generate:
    post:
      summary: Generate a flow
      operationId: generateFlow
      tags:
        - Generate Flow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowGenerateRequest'
      responses:
        '200':
          description: Flow generation request successfully submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowGenerateResponse'
        '400':
          description: Invalid flow type specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /flow/status/{operationId}:
    get:
      summary: Retrieve flow generation status
      operationId: getFlowGenerationStatus
      tags:
        - Generate Flow
      parameters:
        - in: path
          name: operationId
          required: true
          schema:
            type: string
          description: Operation id to get the generation status
      responses:
        '200':
          description: Successfully retrieved the generation status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowGenerateStatus'
        '400':
          description: Invalid operation specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Encountered a server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /flow/result/{operationId}:
    get:
      summary: Retrieve flow generation result
      operationId: getFlowGenerationResult
      tags:
        - Generate Flow
      parameters:
        - in: path
          name: operationId
          required: true
          schema:
            type: string
          description: Operation id to get the generation result
      responses:
        '200':
          description: Successfully retrieved the generation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowGenerateResult'
        '400':
          description: Invalid operation specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Encountered a server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    FlowRequest:
      type: object
      description: Request payload for creating or updating a flow
      required:
        - flowType
        - steps
      properties:
        flowType:
          type: string
          description: Type of the flow being updated
          example: REGISTRATION
        steps:
          type: array
          items:
            $ref: '#/components/schemas/Step'

    FlowGenerateRequest:
      type: object
      description: Request payload for generating a flow
      required:
        - flow_type
        - user_query
      properties:
        flow_type:
          type: string
          description: Type of the flow being updated
          example: REGISTRATION
        user_query:
          type: string
          description: User query to generate the flow
          example: Generate a registration flow with basic details and passkey

    FlowGenerateResponse:
      type: object
      description: Response for generating a flow
      properties:
        operation_id:
          type: string
          description: Id for the submitted generation operation
          example: 2dc32cd4-3cde-4a77-bf95-af55a6738b92

    FlowGenerateStatus:
      type: object
      description: Status response for generating a flow
      properties:
        optimizingQuery:
          type: boolean
          example: true
        fetchingSamples:
          type: boolean
          example: true
        generatingFlow:
          type: boolean
          example: true
        completed:
          type: boolean
          example: true

    FlowGenerateResult:
      type: object
      description: Result response for generating a flow
      properties:
        status:
          type: string
          example: SUCCESS
        data:
          type: object
          properties:
            steps:
              type: array
              items:
                $ref: '#/components/schemas/Step'
            error:
              type: string
              example: Error occurred while generating the flow

    FlowResponse:
      type: object
      description: Response payload for retrieving a flow
      properties:
        steps:
          type: array
          items:
            $ref: '#/components/schemas/Step'

    FlowMetaResponse:
      type: object
      description: General metadata for a flow type
      properties:
        flowType:
          type: string
          example: PASSWORD_RECOVERY
        supportedExecutors:
          type: array
          items:
            type: string
            example: SMSOTPExecutor
        connectorConfigs:
          type: object
        attributeProfile:
          type: string
          example: End-User-Profile
        supportedFlowCompletionConfigs:
          type: array
          items:
            type: string
            example: enableEmailVerification
        attributeMetadata:
          type: array
          items:
            $ref: '#/components/schemas/AttributeMetadata'
        executorConnections:
          type: array
          items:
            $ref: '#/components/schemas/ExecutorConnections'
        workflowEnabled:
          type: boolean
          example: false

    ExecutorConnections:
      type: object
      description: Applicable connections for a given executor
      properties:
        executorName:
          type: string
          description: Name of the executor
          example: OIDCExecutor
        connections:
          type: array
          items:
            type: string
            example: IdpName

    AttributeMetadata:
      type: object
      description: Attribute metadata
      properties:
        name:
          type: string
          example: Username
        claimURI:
          type: string
          example: http://wso2.org/claims/username
        required:
          type: boolean
          example: true
        readOnly:
          type: boolean
          example: true
        validators:
          type: array
          items:
            type: string
            example: AlphanumericValidator

    FlowConfig:
      type: object
      description: Flow configurations for a flow type
      properties:
        flowType:
          type: string
          description: Flow type
          example: REGISTRATION
        isEnabled:
          type: boolean
          description: Indicate whether the orchestration is enabled for the flow
          example: true
        flowCompletionConfigs:
          type: object
          description: Flow Completion Configs.
          additionalProperties:
            type: string
            nullable : false

    FlowConfigPatchModel:
      type: object
      description: Patch model for configurations of a flow type
      required:
        - flowType
      properties:
        flowType:
          type: string
          description: Flow type
          example: REGISTRATION
        isEnabled:
          type: boolean
          description: Indicate whether the orchestration is enabled for the flow
          example: true
        flowCompletionConfigs:
          type: object
          description: Flow Completion Configs.
          additionalProperties:
            type: string
            nullable : false

    Step:
      type: object
      description: Represents a single step in the flow process
      required:
        - id
        - type
        - data
        - size
        - position
      properties:
        id:
          type: string
          description: Unique identifier of the step
          example: dnd-step-3fa85f64-5717-4562-b3fc-2c963f66afa6
        type:
          type: string
          description: Type of the step
          example: VIEW
        data:
          $ref: '#/components/schemas/Data'
        size:
          $ref: '#/components/schemas/Size'
        position:
          $ref: '#/components/schemas/Position'

    Data:
      type: object
      properties:
        components:
          type: array
          items:
            $ref: '#/components/schemas/Component'
        action:
          $ref: '#/components/schemas/Action'

    Component:
      type: object
      description: Represents individual UI components in the flow
      required:
        - id
        - category
        - type
      properties:
        id:
          type: string
          description: Unique identifier of the component
          example: dnd-component-210e95c0-c580-40b0-9646-7054bb340f64
        category:
          type: string
          description: Type of component
          example: FIELD
        type:
          type: string
          description: Specific component type (e.g., INPUT, BUTTON)
          example: INPUT
        variant:
          type: string
          description: Variant of the component (e.g., PRIMARY, TEXT)
          example: PASSWORD
        version:
          type: string
          description: Version of the component
          example: "1.0.0"
        deprecated:
          type: boolean
          description: Indicates whether the component is deprecated
          example: false
        components:
          type: array
          items:
            $ref: '#/components/schemas/Component'
        action:
          $ref: '#/components/schemas/Action'
        config:
          type: object
          description: Configuration details of the component

    Action:
      type: object
      description: Represents an action which controls the flow
      required:
        - type
      properties:
        type:
          type: string
          description: Type of action
          example: EXECUTOR
        executor:
          $ref: '#/components/schemas/Executor'
        next:
          type: string
          description: ID of the next step. For the last step, value will be "COMPLETE"
          example: dnd-step-asd85f64-5717-4562-b3fc-2234f66afa6

    Executor:
      type: object
      description: Represents the execution that an action is going to perform
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the executor
          example: GoogleSignUpExecutor
        meta:
          type: object
          description: Contains metadata related to the executor
          example:
            idp: google1

    Size:
      type: object
      description: Represents the dimensions of a step
      required:
        - height
        - width
      properties:
        height:
          type: number
          example: 200
        width:
          type: number
          example: 160

    Position:
      type: object
      description: Represents the coordinates of a step in the composer canvas
      required:
        - x
        - y
      properties:
        x:
          type: number
          example: 120.12
        y:
          type: number
          example: 200.22

    Error:
      type: object
      properties:
        code:
          type: string
          example: AAA-00000
        message:
          type: string
          example: Some Error Message
        description:
          type: string
          example: Some Error Description
        traceId:
          type: string
          example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047

  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://localhost:9443/oauth2/authorize
          tokenUrl: https://localhost:9443/oauth2/token
          scopes:
            read: internal_flow_mgt_view
            write: internal_flow_mgt_update
