openapi: 3.0.0
info:
  description: >
    This document specifies a **Flow Execution HTTP RPC API** for **WSO2
    Identity Server**.
  version: '1.0'
  title: WSO2 Identity Server - Flow Execution HTTP RPC 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/execute:
    post:
      summary: Execute a flow step
      tags:
        - Execute a flow step
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FlowExecutionRequest"
      responses:
        '200':
          description: Successfully executed the flow step
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowExecutionResponse"
        '400':
          description: Bad request - invalid input or missing required fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        '500':
          description: Internal server error - unexpected failure during flow execution
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  schemas:
    FlowExecutionRequest:
      type: object
      properties:
        flowType:
          type: string
          description: Unique identifier to identify the flow type
          example: REGISTRATION
        applicationId:
          type: string
          description: Unique identifier for the application
          example: 01afc2d2-f7b8-46db-95a9-c17336e7a1c6
        flowId:
          type: string
          description: Unique identifier for the flow execution
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        actionId:
          type: string
          description: Action identifier
          example: button_40f64
        inputs:
          type: object
          description: Input values for the execution step
          example: {
            "username": "johnw"
          }

    FlowExecutionResponse:
      type: object
      required:
        - flowId
        - flowType
        - flowStatus
        - type
      properties:
        flowId:
          type: string
          description: Unique identifier for the flow execution
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        flowType:
          type: string
          description: Unique identifier to identify the flow type
          example: REGISTRATION
        flowStatus:
          type: string
          example: INCOMPLETE
        type:
          type: string
          enum: [VIEW, REDIRECTION, INTERNAL_PROMPT, WEBAUTHN]
          example: VIEW
        data:
          $ref: "#/components/schemas/Data"

    Data:
      type: object
      properties:
        components:
          type: array
          items:
            $ref: "#/components/schemas/Component"
        redirectURL:
          type: string
        requiredParams:
          type: array
          items:
            type: string
        webAuthnData:
          type: object
          description: Data related to WebAuthn operations
          additionalProperties: true
        additionalData:
          type: object
          additionalProperties: true

    Component:
      type: object
      description: Represent individual UI components in the flow execution
      required:
        - id
        - type
      properties:
        id:
          type: string
          description: Unique identifier of the component
          example: button_40f64
        actionId:
          type: string
          description: Action identifier
          example: button_40f64
        type:
          type: string
          description: Specific component type (e.g., INPUT, BUTTON)
          example: INPUT
        variant:
          type: string
          description: Specific component variant
          example: HEADING1
        components:
          type: array
          items:
            $ref: "#/components/schemas/Component"
        config:
          type: object
          description: Configuration details of the component

    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          example: FE-60008
        message:
          type: string
          example: Invalid user inputs.
        description:
          type: string
          example: Invalid user inputs provided for the ASK_PASSWORD request

  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://localhost:9443/oauth2/authorize'
          tokenUrl: 'http://localhost:9443/oauth2/token'
          scopes: {}
