openapi: 3.0.0
info:
  version: v1
  title: WSO2 Identity Server - Action Management Rest API
  description: >
    The Action Management REST API provides a comprehensive interface to manage actions
    within the WSO2 Identity Server. Actions enable the extension of product functionality
    across various workflows, such as access token issuance, password updates, and profile updates.
    This API helps developers and administrators to define and manage actions to meet specific
    business needs.
servers:
  - url: 'https://{server-url}/t/{tenant-domain}/api/server/v1'
    variables:
      server-url:
        default: "localhost:9443"
      tenant-domain:
        default: carbon.super

security:
  - BasicAuth: []
  - OAuth2: []
paths:
  /actions/types:
    get:
      tags:
        - Action Types
      summary: List Action Types
      description: "This API returns the detailed summary of the action types.\n\n
        <b>Scope (Permission) required:</b> ``internal_action_mgt_view``\n\n"
      operationId: getActionTypes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionTypesResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        x-codeSamples:
          - lang: Curl
            source: |
              curl --location 'https://localhost:9443/api/server/v1/actions/types' \
              -H 'Authorization: Basic YWRtaW46YWRtaW4='

  /actions/{actionType}:
    post:
      tags:
        - Actions
      summary: Add Action
      description: "This API creates an action and returns the action details along with the action's unique ID.\n\n
       <b>Scope (Permission) required:</b> ``internal_action_mgt_create``\n\n"
      operationId: createAction
      parameters:
        - name: actionType
          in: path
          description: Name of the Action Type.
          required: true
          schema:
            enum:
              - preIssueAccessToken
              - preUpdatePassword
              - preUpdateProfile
              - preRegistration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionModel'
        description: This represents the information of the action to be created.
        required: true
      responses:
        '201':
          description: Action Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        x-codeSamples:
          - lang: Curl
            source: |
              curl --location 'https://localhost:9443/api/server/v1/actions/{actionType}' \
              -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
              -H 'Content-Type: application/json' \
              -d '{
                  "name": "Access Token Pre Issue",
                  "description": "This is the configuration of pre-action for issuing access token.",
                  "endpoint": {
                      "uri": "https://myextension.com/token",
                      "authentication": {
                          "properties": {
                              "username": "auth_username",
                              "password": "auth_password"
                          },
                          "type": "BASIC"
                      }
                  }
              }'
        x-codegen-request-body-name: body

    get:
      tags:
        - Actions
      summary: List Actions
      description: "This API returns actions according to the action type. \n\n
        <b>Scope (Permission) required:</b> ``internal_action_mgt_view``\n\n"
      operationId: getActionsByActionType
      parameters:
        - name: actionType
          in: path
          description: Name of the Action Type.
          required: true
          schema:
            enum:
              - preIssueAccessToken
              - preUpdatePassword
              - preUpdateProfile
              - preRegistration
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponseList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Curl
          source: |
            curl --location 'https://localhost:9443/api/server/v1/actions/{actionType}' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4='

  /actions/{actionType}/{actionId}:
    get:
      tags:
        - Actions
      operationId: getActionByActionId
      summary: Retrieve Action by ID
      description: "This API provides the capability to retrieve the action by action Id. \n\n
        <b>Scope (Permission) required:</b> ``internal_action_mgt_view``\n\n"
      parameters:
        - name: actionType
          in: path
          description: Name of the Action Type.
          required: true
          schema:
            enum:
              - preIssueAccessToken
              - preUpdatePassword
              - preUpdateProfile
              - preRegistration
        - name: actionId
          in: path
          description: Unique identifier of the action.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Curl
          source: |
            curl --location 'https://localhost:9443/api/server/v1/actions/{actionType}/{actionId}' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4='
    patch:
      tags:
        - Actions
      summary: Update Action
      description: "This API updates an action and return the updated action. \n\n
        <b>Scope (Permission) required:</b> ``internal_action_mgt_update``\n\n"
      operationId: updateAction
      parameters:
        - name: actionType
          in: path
          description: Name of the Action Type.
          required: true
          schema:
            enum:
              - preIssueAccessToken
              - preUpdatePassword
              - preUpdateProfile
              - preRegistration
        - name: actionId
          in: path
          description: Unique identifier of the action.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionUpdateModel'
        description: This represents the action to be updated.
        required: true
      responses:
        '200':
          description: Action Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Curl
          source: |
            curl --location --request PATCH 'https://localhost:9443/api/server/v1/actions/{actionType}/{actionId}' \
            -H 'Content-Type: application/json' \
            -H 'Accept: application/json' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
            -d '{
                "name": "Access Token Pre Issue action",
                "description": "This is the configuration of pre-action for issuing access token from myextensions.com.",
                "endpoint": {
                    "uri": "http://myextensions.com/access-token",
                    "authentication": {
                        "type": "API_KEY",
                        "properties": {
                            "header": "sample_header",
                            "value": "sample_value"
                        }
                    }
                }
            }'
      x-codegen-request-body-name: body

    delete:
      tags:
        - Actions
      summary: Delete Action
      description: "This API deletes an action using the action's type and unique ID. \n\n
        <b>Scope (Permission) required:</b> ``internal_action_mgt_delete``\n\n"
      operationId: deleteAction
      parameters:
        - name: actionType
          in: path
          description: Name of the Action Type.
          required: true
          schema:
            enum:
              - preIssueAccessToken
              - preUpdatePassword
              - preUpdateProfile
              - preRegistration
        - name: actionId
          in: path
          description: Unique identifier of the action.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Action Deleted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Curl
          source: |
            curl --location --request DELETE 'https://localhost:9443/api/server/v1/actions/{actionType}/{actionId}' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4='

  /actions/{actionType}/{actionId}/activate:
    post:
      tags:
        - Actions
      summary: Activate Action
      description: "This API activates an action using the action's type and unique ID. \n\n
        <b>Scope (Permission) required:</b> ``internal_action_mgt_update``\n\n"
      operationId: activateAction
      parameters:
        - name: actionType
          in: path
          description: Name of the Action Type.
          required: true
          schema:
            enum:
              - preIssueAccessToken
              - preUpdatePassword
              - preUpdateProfile
              - preRegistration
        - name: actionId
          in: path
          description: Unique identifier of the action.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Action Activated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionBasicResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Curl
          source: |
            curl --location --request POST 'https://localhost:9443/api/server/v1/actions/{actionType}/{actionId}/activate' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4='

  /actions/{actionType}/{actionId}/deactivate:
    post:
      tags:
        - Actions
      summary: Deactivate Action
      description: "This API deactivates an action using the action's type and unique ID. \n\n
        <b>Scope (Permission) required:</b> ``internal_action_mgt_update``\n\n"
      operationId: deactivateAction
      parameters:
        - name: actionType
          in: path
          description: Name of the Action Type.
          required: true
          schema:
            enum:
              - preIssueAccessToken
              - preUpdatePassword
              - preUpdateProfile
              - preRegistration
        - name: actionId
          in: path
          description: Unique identifier of the action.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Action Deactivated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionBasicResponse'
              example:
                id: "24f64d17-9824-4e28-8413-de45728d8e84"
                type: "PRE_ISSUE_ACCESS_TOKEN"
                name: "Access Token Pre Issue"
                description: "This action is executed before issuing an access token."
                status: "INACTIVE"
                links:
                  - href: "/api/server/v1/actions/preIssueAccessToken/24f64d17-9824-4e28-8413-de45728d8e84"
                    method: GET
                    rel: self
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Curl
          source: |
            curl --location --request POST 'https://localhost:9443/api/server/v1/actions/{actionType}/{actionId}/deactivate' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4='

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://localhost:9443/oauth2/authorize'
          tokenUrl: 'http://localhost:9443/oauth2/token'
          scopes:
            read: internal_action_mgt_view
            write: internal_action_mgt_create
            update: internal_action_mgt_update
            delete: internal_action_mgt_delete

  schemas:
    ActionType:
      type: string
      description: Action types supported. As of now only 'PRE_ISSUE_ACCESS_TOKEN' is implemented.
      enum:
        - PRE_ISSUE_ACCESS_TOKEN
        - PRE_UPDATE_PASSWORD
        - PRE_UPDATE_PROFILE
        - PRE_REGISTRATION
    ActionModel:
      type: object
      required:
        - name
        - endpoint
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Name of the action.
          example: Pre Issue Access Token Action
        description:
          type: string
          maxLength: 255
          description: Description of the action.
          example: This action invokes before issuing an access token.
        endpoint:
          $ref: '#/components/schemas/Endpoint'
        rule:
          $ref: '#/components/schemas/ORRule'

    Endpoint:
      type: object
      description: Endpoint configurations of the action.
      required:
        - uri
        - authentication
      properties:
        uri:
          type: string
          description: HTTPS URI of the endpoint.
          pattern: '^https?://.+'
          example: https://myextension.com/token
        authentication:
          $ref: '#/components/schemas/AuthenticationType'

    EndpointResponse:
      type: object
      description: Endpoint configurations of the action.
      required:
        - uri
        - authentication
      properties:
        uri:
          type: string
          description: HTTPS URI of the endpoint.
          pattern: '^https?://.+'
          example: https://myextension.com/token
        authentication:
          $ref: '#/components/schemas/AuthenticationTypeResponse'

    ActionResponse:
      type: object
      properties:
        id:
          type: string
          example: '24f64d17-9824-4e28-8413-de45728d8e84'
          description: Unique identifier of the action.
        type:
          $ref: '#/components/schemas/ActionType'
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Name of the action.
          example: Access Token Pre Issue
        description:
          type: string
          maxLength: 255
          description: Description of the action.
          example: This action invokes before issuing an access token.
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Status of the action.
          example: ACTIVE
        endpoint:
          $ref: '#/components/schemas/EndpointResponse'
        rule:
          $ref: '#/components/schemas/ORRuleResponse'

    ActionBasicResponse:
      type: object
      properties:
        id:
          type: string
          example: '24f64d17-9824-4e28-8413-de45728d8e84'
          description: Unique identifier of the action.
        type:
          $ref: '#/components/schemas/ActionType'
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Name of the action.
          example: Access Token Pre Issue
        description:
          type: string
          maxLength: 255
          description: Description of the action.
          example: This action invokes before issuing an access token.
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Status of the action.
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
          example:
            - href: "/api/server/v1/actions/preIssueAccessToken/24f64d17-9824-4e28-8413-de45728d8e84"
              method: GET
              rel: self

    Link:
      type: object
      properties:
        href:
          type: string
          description: Url of the endpoint.
        method:
          type: string
          enum:
            - GET
          description: Http method.
        rel:
          type: string
          description: Relation to the resource.

    ActionResponseList:
      type: array
      items:
        $ref: '#/components/schemas/ActionBasicResponse'

    ActionTypesResponse:
      type: array
      items:
        $ref: '#/components/schemas/ActionTypesResponseItem'

    ActionTypesResponseItem:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ActionType'
        displayName:
          type: string
          description: "Display name of the action type."
          example: "Pre Issue Access Token."
        description:
          type: string
          description: "Description of the action type."
          example: "Extension point configuration for Pre Issue Access Token."
        count:
          type: integer
          description: "Number of actions configured under the action type."
          example: 1
        self:
          type: string
          description: "API endpoint referring to the location of the given action type."
          example: "/api/server/v1/actions/preIssueAccessToken/24f64d17-9824-4e28-8413-de45728d8e84"

    AuthenticationType:
      type: object
      description: >
        The type of authentication required by the action's endpoint. The following options are supported:
        
        - NONE: No authentication is required. <br>
          ``{
            "type": "NONE"
          }``
        
        - BASIC: Basic authentication with a username and password.<br>
          ``{
            "type": "BASIC",
            "properties": {
              "username": "auth_username",
              "password": "auth_password"
            }
          }``
        
        - API_KEY: API key-based authentication, where the key is provided in an HTTP header.<br>
          ``{
            "type": "API_KEY",
            "properties": {
              "header": "X-API-Key",
              "value": "12345-abcde-67890"
            }
          }``
        
        - BEARER: Bearer token-based authentication.<br/>
          ``{
            "type": "BEARER",
            "properties": {
              "accessToken": "0d6fed02-eac0-332b-8998-213a543139a0"
            }
          }``
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
          example: BASIC
        properties:
          type: object
          description: Authentication properties specific to the selected type.
          additionalProperties: true
      example:
        type: BASIC
        properties:
          username: "auth_username"
          password: "auth_password"

    AuthenticationTypeResponse:
      type: object
      description: Authentication configurations of the action.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
          description: Type of the authentication.
          example: BASIC

    ActionUpdateModel:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Updating name of the action.
          example: Pre Issue Access Token Action
        description:
          type: string
          maxLength: 255
          description: Updating description of the action.
          example: This action invokes before issuing an access token.
        endpoint:
          $ref: '#/components/schemas/EndpointUpdateModel'
        rule:
          $ref: '#/components/schemas/ORRule'

    EndpointUpdateModel:
      type: object
      description: Updating endpoint configurations of the action.
      properties:
        uri:
          type: string
          pattern: '^https?://.+'
          description: Updating HTTPS URI of the endpoint.
          example: https://myextension.com/token

        authentication:
          $ref: '#/components/schemas/AuthenticationType'

    ORRule:
      type: object
      description: Represents a rule configuration that combines multiple sub-rules with an OR condition.
        If any of the sub-rules evaluate to true, the ORRule is considered satisfied.
      properties:
        condition:
          type: string
          description: The logical condition for combining the sub-rules. For ORRule, the value
            must always be "OR".
          enum: ["OR"]
        rules:
          type: array
          items:
            $ref: '#/components/schemas/ANDRule'
          minItems: 1

    ORRuleResponse:
      type: object
      description: Rule configured for the action.
      properties:
        condition:
          type: string
          enum: ["OR"]
        rules:
          type: array
          items:
            $ref: '#/components/schemas/ANDRuleResponse'
          description: A list of sub-rules that are combined using the OR condition. Each sub-rule is an ANDRule.
          minItems: 1

    ANDRule:
      type: object
      description: A sub-rule that combines expressions with AND condition.
      required:
        - condition
        - expressions
      properties:
        condition:
          type: string
          enum: ["AND"]
          description: The logical condition for combining the expressions. For ANDRule, the value must always be "AND".
        expressions:
          type: array
          items:
            $ref: '#/components/schemas/Expression'
          minItems: 1
          description: A list of expressions that are combined using the AND condition. All expressions must evaluate to true for the ANDRule to pass.

    ANDRuleResponse:
      type: object
      description:  Represents a rule configuration that combines multiple expressions with an AND condition. All expressions in the ANDRule must evaluate to true for the rule to be satisfied.
      properties:
        condition:
          type: string
          enum: ["AND"]
          description: The logical condition for combining the expressions. For ANDRule, the value must always be "AND".
        expressions:
          type: array
          items:
            $ref: '#/components/schemas/ExpressionResponse'
          minItems: 1
          description: A list of expressions that are combined using the AND condition. All expressions must evaluate to true for the ANDRule to pass.

    Expression:
      type: object
      description: Represents a single logical condition or comparison within a rule. An expression defines a field, an operator, and a value that is evaluated.
      required:
        - field
        - operator
        - value
      properties:
        field:
          type: string
          description: The field or attribute of the entity being evaluated (e.g.,application, role).
          example: application
        operator:
          type: string
          description: The comparison operator used to evaluate the field and value. Common operators include "equals", "contains", "startsWith", etc.
          example: equals
        value:
          type: string
          description: The value that the field is compared against based on the operator.
          example: myapp

    ExpressionResponse:
      type: object
      description: Expressions in the rule.
      properties:
        field:
          type: string
          example: application
        operator:
          type: string
          example: equals
        value:
          type: string
          example: myapp

    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
